Using IconVectors with Claude / Anthropic

This page explains the recommended local setup for Claude Desktop and Claude Code. Windows and macOS can use Claude Desktop or Claude Code. On Linux, use Claude Code. As of IconVectors 1.50, the public MCP tool naming is compatible with Claude clients.

Overview

IconVectors includes a desktop editor (IconVectors.exe) and a companion MCP server (IconVectorsMcp.exe).

For Claude products, the clean integration pattern is:

  1. Start IconVectors.exe normally so its local bridge is available.

  2. For Claude Desktop, install the supplied Axialis-IconVectors-Claude.mcpb extension bundle.

  3. For Claude Code, add IconVectorsMcp.exe --port <port> as a local stdio MCP server.

  4. Keep the port the same on both sides.

See also MCP Integration.

Before you begin

Make sure these files are available:

  • application files in C:\Program Files\Axialis\IconVectors:

    • IconVectors.exe

    • IconVectorsMcp.exe

    • Axialis-IconVectors-Claude.mcpb

  • Linux packaged install:

    • /usr/bin/IconVectors

    • /usr/bin/IconVectorsMcp

  • helper files in %APPDATA%\Axialis\IconVectors\MCP:

    • iconvectors-mcp-tools.json

    • claude-implementation-instructions.md

    • iconvectors-mcp-command-reference.md

    • claude-CLAUDE.md.template

  • Linux helper files in ~/.local/share/Axialis/IconVectors/MCP:

    • claude-implementation-instructions.md

    • iconvectors-mcp-command-reference.md

    • claude-CLAUDE.md.template

Keeping the helper files in the per-user MCP folder is a better fit than putting them beside the executables.

You can open that folder directly from IconVectors with Help ‣ Open MCP Files Folder.

Important: Claude does not import the helper markdown or JSON files automatically.

  • Claude Desktop uses the provided .mcpb extension bundle.

  • Claude Code uses claude mcp add or claude mcp add-json.

  • On Linux, Claude Desktop is not available. Use Claude Code with the local stdio MCP server.

  • The shipped JSON file is best treated as a reference/diagnostic manifest that stays version-matched with the installed server.

If your installation includes the optional MCP helper files, the most useful Claude files are:

  • %APPDATA%\Axialis\IconVectors\MCP\claude-implementation-instructions.md

  • %APPDATA%\Axialis\IconVectors\MCP\iconvectors-mcp-command-reference.md

  • %APPDATA%\Axialis\IconVectors\MCP\claude-CLAUDE.md.template

Use them like this:

  • open claude-implementation-instructions.md for the step-by-step Claude setup,

  • keep iconvectors-mcp-command-reference.md nearby if you want the AI to see the full tool surface in plain text,

  • copy claude-CLAUDE.md.template to CLAUDE.md in your repository if you want Claude Code to prefer the IconVectors MCP tools for icon work.

Claude Code’s native repository instruction file is CLAUDE.md. A generic project-root SKILL.md is not the main format to rely on for Claude users here.

Start IconVectors

Start the editor first:

.\IconVectors.exe

On Linux:

/usr/bin/IconVectors

For Claude Desktop and Claude Code, do not normally start the editor with --mcp.

Those clients are designed to launch the MCP server process themselves. In practice, that means:

  • IconVectors.exe runs the editor and local bridge.

  • Claude Desktop launches the packaged MCP extension.

  • Claude Code launches IconVectorsMcp.exe --port 61337 when needed.

Use IconVectors.exe --mcp only for manual standalone testing outside Claude.

If you changed the default bridge port through ICONVECTORS_MCP_PORT or app configuration, use that same port for Claude Code and any related testing.

Claude Desktop setup

Claude Desktop should use the supplied extension bundle, not claude_desktop_config.json.

Install the platform-specific Axialis-IconVectors-Claude.mcpb file provided with your IconVectors build. On Windows, the file is stored in the application folder beside IconVectors.exe:

C:\Program Files\Axialis\IconVectors\Axialis-IconVectors-Claude.mcpb

On macOS, use the matching .mcpb file provided with the build or package you installed.

Claude Desktop is not currently available on Linux. On Linux, skip this section and use Claude Code setup below.

  1. Start IconVectors.exe.

  2. Open Claude Desktop.

  3. Go to Settings ‣ Extensions ‣ Advanced settings ‣ Install Extension….

  4. Select Axialis-IconVectors-Claude.mcpb.

  5. Restart Claude Desktop.

Notes:

  • Do not point Install Extension… at IconVectorsMcp.exe directly. Claude expects a .mcpb package.

  • If you install an updated IconVectors MCP bundle later, reinstall the newer .mcpb and restart Claude Desktop.

  • The extension bundle contains the MCP server metadata Claude Desktop needs in order to launch the local helper.

Verify in Claude Desktop

After restart, verify the extension in one or more of these places:

  • Settings ‣ Extensions

  • Settings ‣ Developer

  • a chat window via the + button, then Connectors

Good first prompts:

  • Use IconVectors to call app_ping.

  • Use IconVectors to call app_getInfo.

  • Create a new 32x32 icon, use the current palette, draw a simple centered shape, and export it as SVG.

Saving And Exporting On Windows

When Claude asks IconVectors on Windows to write a file, use a native Windows path such as:

  • C:\Users\[username]\Downloads\home-icon.svg

  • C:\Users\[username]\Desktop\home-icon.svg

Do not use Claude sandbox paths such as:

  • /mnt/user-data/outputs/home-icon.svg

Those paths belong to Claude’s own environment, not to the Windows desktop application.

If you want Claude to keep the result inside its own workspace or preview flow, prefer:

  • document_getSvg

and let Claude save the returned SVG content itself.

Claude Code setup

Claude Code supports local stdio MCP servers directly.

Windows:

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

macOS:

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

Linux:

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

Then verify it:

claude mcp list

Inside Claude Code, use:

/mcp

That shows server status and management options.

Alternative: add from JSON

Claude Code can also add an MCP server from a server-configuration JSON object:

claude mcp add-json iconvectors '{"type":"stdio","command":"C:\\Program Files\\Axialis\\IconVectors\\IconVectorsMcp.exe","args":["--port","61337"],"env":{}}' --scope user

This is not the same as the shipped iconvectors-mcp-tools.json file. claude mcp add-json expects a server configuration object, not a full tool-manifest/specification file.

Optional: share config with a project

If you want a repository to carry the IconVectors MCP setup for the whole team, use a project-scoped .mcp.json file in the repository root.

Example:

{
  "mcpServers": {
    "iconvectors": {
      "type": "stdio",
      "command": "${ICONVECTORS_HOME}/IconVectorsMcp.exe",
      "args": ["--port", "61337"],
      "env": {}
    }
  }
}

This works best if each developer defines ICONVECTORS_HOME locally.

Optional: guide Claude with a CLAUDE.md file

If you want Claude Code to prefer IconVectors for icon and SVG tasks, start from the installed template:

  • %APPDATA%\Axialis\IconVectors\MCP\claude-CLAUDE.md.template

Copy it to your repository root as CLAUDE.md.

Anthropic API / Claude web note

The current local sidecar design is a good fit for:

  • Claude Desktop

  • Claude Code

It is not directly usable with Anthropic’s hosted API connector, because that integration expects a public HTTP-accessible MCP server. Local stdio servers cannot be attached directly.

For Anthropic API usage, you have two paths:

  • Remote HTTP MCP wrapper - Expose IconVectors through a remote HTTPS MCP server that can reach the desktop app or another backend service.

  • Your own local client using the Anthropic SDK - Build a small client application that talks to IconVectorsMcp.exe over local stdio and forwards the tools to Anthropic yourself.

Troubleshooting

If Claude Desktop does not show the server:

  • Confirm IconVectors.exe is already running.

  • Confirm the supplied Axialis-IconVectors-Claude.mcpb bundle was installed successfully.

  • Reinstall the latest .mcpb if you recently updated IconVectors.

  • Check Settings ‣ Extensions and Settings ‣ Developer.

  • Do not try to install IconVectorsMcp.exe directly through the extension UI.

  • On Windows, if Claude tries to save to /mnt/user-data/..., ask it to use a native Windows path or use document_getSvg instead.

  • On Linux, use Claude Code instead of Claude Desktop.

If Claude Code does not see the server:

  • Run claude mcp list.

  • Open /mcp inside Claude Code.

  • Re-add the server using the full executable path.

  • Prefer --scope user if you want the server available across projects.

  • On Linux packaged installs, the expected executable path is /usr/bin/IconVectorsMcp.

If the server starts but behaves oddly:

  • Make sure IconVectorsMcp.exe resolves sibling files from its executable directory.

  • Avoid assumptions about the current working directory.

  • Test the server manually from PowerShell:

    .\IconVectorsMcp.exe --port 61337