Using IconVectors with Claude

Ask Claude for an icon in a chat and you get SVG text to paste, fix and re-check by hand. Connect Claude to IconVectors over the local MCP bridge and it works inside the running editor instead: it inspects the live document, creates and edits geometry, runs document_analyzeCleanupSvg, renders previews, exports files, and in 2.0+ it can browse the Icon Explorer and run the batch tools.

This guide covers both clients on IconVectors 2.0+ for Windows. Claude Desktop installs one .mcpb extension bundle; Claude Code registers the same stdio helper from the command line. The macOS and Linux builds of 2.00 are coming soon; the current 1.70 builds ship the same helper (the .mcpb in the macOS package, /usr/bin/IconVectorsMcp on Linux), without the Explorer and batch tools until 2.00 reaches those platforms.

1. Start IconVectors first

Launch IconVectors normally and leave it running. IconVectorsMcp.exe is installed beside IconVectors.exe; Claude launches it, and it forwards each call over loopback (127.0.0.1:61337 unless you changed Options/McpPort) to the application. With two IconVectors windows open, only the one that owns the configured port answers, and there is no instance picker.

2. Set up Claude Desktop

The shipped bundle is the preferred route, because it carries the server definition with it and saves you a hand-written configuration:

1. In Claude Desktop, open Settings -> Extensions -> Advanced settings -> Install Extension.
2. Select C:\Program Files\Axialis\IconVectors\Axialis-IconVectors-Claude.mcpb. Do not select IconVectorsMcp.exe in that dialog; the bundle already points at it.
3. Check that the extension and its server appear in Settings, and approve the server when Claude asks.

Reinstall the bundle after an IconVectors update when its packaged server metadata changes. A restart of Claude Desktop is only needed when troubleshooting calls for it. On macOS with 1.70, the same bundle ships with the application package and installs through the same dialog; Claude Desktop is not available on Linux, so Linux users go straight to Claude Code.

3. Set up Claude Code

Register the helper as a user-scoped stdio server. Options come before the server name, and the -- separates the helper command from Claude's own arguments:

Windows (2.0+)

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

macOS (1.70 helper)

claude mcp add --transport stdio --scope user iconvectors -- /Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp --port 61337

Linux (1.70 helper)

claude mcp add --transport stdio --scope user iconvectors -- /usr/bin/IconVectorsMcp --port 61337

User-scoped servers land in ~/.claude.json. A project can share one through .mcp.json instead; review that file before you approve it, because project servers ask for approval the first time. In a session, /mcp shows server status and the project-server trust choices, and claude mcp reset-project-choices forgets saved approvals when you want to review them again.

4. Verify the connection

In Claude Desktop, check the extension and server in Settings. In Claude Code, run claude mcp list and /mcp. Then ask for the four discovery calls:

• Use the iconvectors server to call app_ping and tell me whether IconVectors answered.
• Call app_getInfo and app_getCapabilities and summarize the running instance.
• Call app_get_workspace and tell me whether the Editor or the Explorer is active.

Before any change, have Claude inspect the state it is about to touch: document_getInfo and selection_get in the Editor, or explorer_get_state and explorer_list_entries in the Explorer.

5. Install the instructions and the skill

Copy claude-CLAUDE.md.template to CLAUDE.md or .claude/CLAUDE.md in the project. User-level instructions can live in ~/.claude/CLAUDE.md, and a repository that already keeps shared instructions in AGENTS.md can pull them in with an @AGENTS.md import. Help -> Open MCP Files Folder in IconVectors opens the per-user MCP helper-files folder, the first place to look for the template and for the skill.

Then install the complete iconvectors-mcp skill, references directory included, at one of these locations:

• project: .claude/skills/iconvectors-mcp/SKILL.md
• user: ~/.claude/skills/iconvectors-mcp/SKILL.md

Keep CLAUDE.md short. The tool catalog does not belong in it; the skill and the installed command reference carry that.

6. Make a first bounded edit

1. Ask Claude to call document_getInfo and selection_get and describe what it sees.
2. Ask for one simple shape, or one property change on the selected element.
3. Have it reinspect the element, the selection and the document.
4. Save or export only when you ask, and only to a native Windows path such as C:\Users\name\Downloads\icon.svg. A Claude sandbox path like /mnt/user-data/... is not visible to the desktop application. If Claude should keep the SVG on its side instead, ask for document_getSvg and let it handle the text.

For related edits, one history transaction: history_beginTransaction returns a txId, the edits follow, and history_commitTransaction or history_rollbackTransaction gets that exact ID. Save and export, document replacement and Explorer file changes are outside document Undo, and the replacement tools (document_new, document_open, document_setSvg) also clear the Undo history.

Working with 155 tools

Claude is naming-compatible with all 155 production tools under their canonical underscore names; nothing needs renaming. Claude Code uses Tool Search for large MCP catalogs and publishes no fixed per-server ceiling, so IconVectors needs no special profile for it. A task-focused selection still reduces ambiguity when you can make one. Output is the limit to watch: Claude Code warns when an MCP result passes 10,000 tokens, stops at 25,000 by default, and lets you raise that with MAX_MCP_OUTPUT_TOKENS. Prefer bounded queries and minified SVG over full documents and base64 previews.

Approvals and safety

Project servers require approval, and a permission pattern such as mcp__iconvectors__* can cover the whole server. Do not use it for the calls Undo cannot fix: Save As, export, document replacement, Explorer file changes, batch apply. Start with prompts, and keep the inspect, mutate, verify order. Approval is a Claude policy; it does not change what IconVectors does with the call.

Troubleshooting

Claude Desktop does not show the server

Confirm the .mcpb is installed and enabled, then look in the Extensions or Developer settings. Reinstall the current bundle, and restart only if that does not help.

Claude Code does not show the server

Run claude mcp list and /mcp. Check the scope you registered in, the command path, and project trust for a .mcp.json server.

The connection is refused or times out

Start IconVectors, match the port, and check that another instance did not claim it. MCP_TIMEOUT controls how long Claude Code waits for the server to start; the helper's own bridge to the application has a separate 10-second send and receive timeout.

Wrong document, workspace or selection

Inspect again. Do not force a replacement, invent a selection, or assume an Explorer navigation has settled: a navigation that returns status: "accepted" has started, and explorer_get_state tells you when it is done.

You need logs

Use the Claude Desktop developer and extension diagnostics, or /mcp status in Claude Code. IconVectors does not write a separate helper log file. When the catalog or an answer is too large, ask for bounded results.

For current client behavior, see the official Claude Code MCP documentation.

If IconVectors is not installed yet, download the free trial and run the first bounded edit with an icon open.