Using IconVectors with Gemini CLI

Overview

Gemini CLI can inspect and control IconVectors 2.00 through a local stdio MCP server on Windows. Gemini launches IconVectorsMcp.exe; the sidecar forwards calls over loopback to the already-running desktop application.

This gives Gemini CLI access to the current Editor document and selection, Icon Explorer, SVG editing, preview/export, history, and Explorer Batch Starter operations. See MCP Integration for shared behavior and safety guidance.

Prerequisites

  • Install Gemini CLI on the same Windows machine as IconVectors.

  • Start IconVectors 2.00 normally and leave it running.

  • Confirm IconVectorsMcp.exe exists beside IconVectors.exe.

  • The default bridge is 127.0.0.1:61337. Match a custom Options/McpPort value if necessary.

  • Use native Windows paths visible to the desktop application.

Configure Gemini CLI

Use .gemini/settings.json for project scope or %USERPROFILE%\.gemini\settings.json for user scope. The recommended server name is iconvectors:

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

The path is the normal installed-product example. Replace it or the port when needed.

The equivalent CLI route defaults to project scope; add --scope user for user scope:

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

Verify the connection

In an interactive session, use /mcp or /mcp list for servers, /tools for registered tools, and /mcp reload after a configuration change. Then call:

  • app_ping

  • app_getInfo

  • app_getCapabilities

  • app_get_workspace

Inspect the active document and selection or Explorer state before making a change.

Install the IconVectors skill

Copy the complete distributed iconvectors-mcp skill, including its references directory, to:

  • workspace: .agents/skills/iconvectors-mcp/SKILL.md

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

Gemini CLI discovers this interoperable skill location. Use /skills list and /skills reload to verify it. Keep GEMINI.md limited to short persistent context or a pointer to the skill; do not paste the workflow or complete catalog there.

First workflow

Try one bounded Editor operation:

  1. Inspect document_getInfo and selection_get.

  2. Create one simple element or change one selected element.

  3. Reinspect the returned element and document state.

  4. Save or export only when you explicitly requested a native Windows destination.

For several compatible document edits, use a history transaction and its exact returned txId. Transactions do not include save/export, replacement, or Explorer filesystem operations.

Working with 155 tools

Gemini CLI is naming-compatible with 155/155 production IconVectors tools. With the server name iconvectors, all model-facing names remain unique: there are no sanitizations, truncations, or collisions. No shorter alias or tool rename is needed. Avoid underscores in the server alias because Gemini’s policy parser uses them as separators.

Gemini CLI does not document on-demand MCP Tool Search. To reduce the task catalog, add includeTools with raw IconVectors tool names or use excludeTools. An exclusion wins when both lists mention a tool. For example, a temporary discovery-only server entry can include:

"includeTools": [
  "app_ping",
  "app_getInfo",
  "app_getCapabilities",
  "app_get_workspace"
]

Expand that client-side list for the intended Editor, Explorer, Path, Paint, Export, or Batch task. IconVectors itself does not serve named profiles.

Trust and approvals

Keep trust: false while evaluating the server. A trusted MCP server can bypass tool-call confirmation. Workspace trust is separate, and an untrusted workspace does not start stdio servers.

Continue prompting for document replacement, save/export, Explorer disk operations, and batch apply. Trust is a client policy, not an Undo guarantee.

Troubleshooting

Server is absent

Check gemini mcp list, JSON scope, workspace trust, the absolute executable path, and the port.

Sidecar connects but calls fail

Start IconVectors, match the bridge port, and use app_getInfo to verify the intended application instance.

Wrong state

Reinspect workspace, document, selection, or Explorer state. Do not guess a recovery mutation or force document replacement.

Path fails

Pass an absolute native Windows path and preserve JSON escaping for spaces, Unicode, and backslashes.

Catalog or output is too large

Use includeTools or excludeTools and bounded DOM/Explorer queries. Avoid full SVG or base64 output unless required.

For current client commands, see the official Gemini CLI MCP documentation.