Using IconVectors with Gemini CLI

Gemini CLI can read and edit the icon that is open in IconVectors 2.0+, instead of working from SVG markup you paste into the chat. This guide is for IconVectors 2.0+ on Windows. The macOS and Linux 2.00 builds are coming soon.

The moving parts fit in one sentence: Gemini CLI launches IconVectorsMcp.exe as a stdio MCP server, and that helper forwards each call over loopback (127.0.0.1:61337 by default) to the IconVectors window already running on your desktop. Through it, Gemini reaches the current Editor document and selection, Icon Explorer, SVG editing, preview and export, history, and the Explorer batch tools. That is 155 tools, and Gemini CLI can use every one of them under its real name.

1. Start IconVectors

Launch the app the normal way and leave it running. From PowerShell:

& 'C:\Program Files\Axialis\IconVectors\IconVectors.exe'

IconVectorsMcp.exe sits next to IconVectors.exe in the install folder. Do not start it yourself and do not register it as a background service; Gemini launches it, and it does nothing but forward calls to the app. The app listens on 127.0.0.1:61337 unless you changed Options/McpPort. If you did, note the value, because the helper needs the same port in the next step.

One more thing about ports: with several IconVectors windows open, only the instance that owns the configured port answers, and there is no instance picker. Keep a single window open while you evaluate, or give each instance its own port.

2. Register the server in Gemini CLI

Gemini CLI reads MCP servers from settings.json. Use .gemini/settings.json inside the project for a project-scoped server, or %USERPROFILE%\.gemini\settings.json to make it available everywhere. Name the server iconvectors; everything on this page assumes that alias.

{
  "mcpServers": {
    "iconvectors": {
      "command": "C:\\Program Files\\Axialis\\IconVectors\\IconVectorsMcp.exe",
      "args": ["--port", "61337"],
      "trust": false
    }
  }
}

The command is the default install path; change it if IconVectors lives somewhere else, and change the port if Options/McpPort is not 61337. The backslashes are doubled because this is JSON. "trust": false is deliberate, and the trust section below explains why you want to keep it that way for a while.

If you would rather not edit JSON by hand, gemini mcp add writes the same entry. It defaults to project scope, so add --scope user for the user file. Everything after the -- goes to the helper as its own arguments.

gemini mcp add --scope user iconvectors "C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe" -- --port 61337
gemini mcp list

gemini mcp list is also the first thing to run when something does not connect later.

3. Verify the connection

Start an interactive gemini session and check the server from inside it. Three slash commands cover it:

• /mcp or /mcp list shows the configured servers and their state.
• /tools shows the registered tools. This is where the 155 IconVectors names should appear.
• /mcp reload re-reads the configuration after you edit settings.json or run gemini mcp add.

Then ask Gemini to make the four discovery calls, in this order. The first proves the helper can reach the app, the second identifies which IconVectors instance answered, and the last two tell the model what this build supports and whether the app is currently in the Editor or in Icon Explorer.

• Use the iconvectors MCP server to call app_ping and tell me whether IconVectors answered.
• Call app_getInfo on the iconvectors server and summarize what it reports about the running instance.
• Call app_getCapabilities and list what this IconVectors build supports.
• Call app_get_workspace and tell me whether IconVectors is in the Editor or in Icon Explorer.

Stop there before asking for an edit. The next thing to inspect is the state you are about to change: document_getInfo and selection_get in the Editor, or explorer_get_state and explorer_list_entries in Icon Explorer.

4. Install the iconvectors-mcp skill

The iconvectors-mcp skill we distribute for 2.0+ holds the inspect, mutate, recover and verify workflow the model should follow, plus a references folder. Copy the whole folder, references included; SKILL.md on its own leaves out the material it refers to.

Put it in one of the two locations Gemini CLI scans:

• workspace: .agents/skills/iconvectors-mcp/SKILL.md
• user: %USERPROFILE%\.agents\skills\iconvectors-mcp\SKILL.md

.agents/skills is an interoperable skill location, so Gemini CLI discovers the skill there without any extra configuration. Confirm with /skills list; if you copied the folder while a session was already open, run /skills reload first.

Keep GEMINI.md short. It is the right place for one line of always-on policy or a pointer to the skill, and the wrong place for the workflow or the tool catalog.

5. Make a first bounded edit

Open an icon in the Editor and run one small change through the full loop: inspect, change one thing, inspect again.

1. Ask Gemini to call document_getInfo and selection_get and to describe what it sees before it touches anything.
2. Ask for one change: create one simple element, or change one property of the element you have selected.
3. Have it reinspect the element it just returned and the document state, and compare that with what you asked for.
4. Save or export only when you ask for it, and give it an absolute native Windows destination such as C:\Projects\icons\logo.svg. Do not let it pick a path.

Two details matter once the edits get bigger. Element ordinals are live positions in the document, not permanent IDs: creating, deleting, reordering or reparenting elements can make an ordinal the model saw earlier stale, so after anything structural it should reinspect rather than reuse the old target.

And when one task needs several related edits, wrap them in a history transaction. The model calls history_beginTransaction, keeps the txId it returns, makes the edits, then passes that exact ID to history_commitTransaction, or to history_rollbackTransaction if a step failed. Do not leave a transaction open and do not mix unrelated work into one. Transactions cover active-document edits only. Save and export, document replacement (document_new, document_open, document_setSvg) and Explorer file operations sit outside document Undo, and the three replacement tools also clear the Undo history.

Working with 155 tools

Gemini CLI is naming-compatible with all 155 production IconVectors tools. With the server named iconvectors, every model-facing name stays unique: nothing is sanitized, truncated or renamed, and nothing collides, so there is no need for a shorter alias. The one naming rule that does matter is the alias itself. Gemini's policy parser uses underscores as separators, so iconvectors is safe and icon_vectors is not.

Gemini CLI documents no on-demand Tool Search, so unless you trim the list yourself, all 155 tools are registered in every session. The trimming is client-side, with two keys on the server entry: includeTools, an allowlist of raw IconVectors tool names, and excludeTools. When a tool appears in both lists, the exclusion wins. A discovery-only entry for a first session looks like this:

{
  "mcpServers": {
    "iconvectors": {
      "command": "C:\\Program Files\\Axialis\\IconVectors\\IconVectorsMcp.exe",
      "args": ["--port", "61337"],
      "trust": false,
      "includeTools": [
        "app_ping",
        "app_getInfo",
        "app_getCapabilities",
        "app_get_workspace"
      ]
    }
  }
}

Widen that list for the job at hand: document, selection, creation, style, element, history and preview tools for ordinary editing; inspection, DOM, path, history and preview tools for path work; code, render and export tools for output; workspace discovery plus the Explorer tools for batch work. Whatever you choose, keep the four discovery calls and the state-inspection tools in the active set. IconVectors itself serves no named profiles; the filter lives entirely in Gemini's settings.

Trust and approvals

Leave "trust": false in place while you evaluate. Two things make trust awkward here, and both are Gemini policy rather than IconVectors behavior. A trusted MCP server can bypass tool-call confirmation, which means a trust: true entry can let Gemini save, export or replace a document without asking you first. Workspace trust is a separate switch, and it cuts the other way: in an untrusted workspace Gemini CLI does not start stdio servers at all, so the iconvectors entry never connects until you trust the folder.

Keep the confirmation prompts for anything that changes a file or replaces a document: document_setSvg, save and export, Explorer create, rename, delete, paste and duplicate, and batch apply. Read the tool name and its arguments when Gemini asks. The batch tools plan first and apply second, so check the plan summary, its diagnostics and the returned plan_id before approving the apply; a rejected apply consumes the plan, and the fix is a new plan, not a retry with the old ID.

Trust is a client policy, not an Undo guarantee. If it is unclear which document, selection, folder or IconVectors instance a call is aimed at, have the model inspect again or ask you, instead of approving everything to make the prompts go away.

Troubleshooting

The server is absent. Run gemini mcp list. If the entry is missing, check which settings.json you edited (project or user) and the JSON itself. If it is listed but never connects, check workspace trust, the absolute path to IconVectorsMcp.exe with its doubled backslashes, and the port.

The helper connects but calls fail. Usually IconVectors is not running, or it is listening on a different port. Start it, match Options/McpPort, then call app_getInfo to confirm you are talking to the instance you expect. The helper's own send and receive timeout to the app is 10 seconds, separate from any startup or request timeout Gemini applies to the helper process.

The state looks wrong. Reinspect the workspace, document, selection or Explorer state. Do not let the model guess a recovery mutation or force a document replacement to get back to a known state.

A path fails. Pass an absolute native Windows path and keep the JSON escaping intact for spaces, Unicode and backslashes. A path that only exists inside a sandbox, a container or WSL is not one the desktop app can see.

The catalog or the output is too large. Use includeTools or excludeTools, and ask for bounded DOM or Explorer queries. Skip full SVG and base64 output unless you need it. IconVectors does not write a separate helper log; whatever Gemini reports about the server is the diagnostic to read.

For the current client-side commands and settings keys, see the official Gemini CLI MCP documentation.

If IconVectors is not installed yet, download the free trial and work through the five steps above with a real icon open.