Using IconVectors with Cursor

Feeding SVG markup to a chat means the model never sees what is on your canvas. Wire Cursor to the IconVectors MCP helper and Cursor reads and edits the document that is open in the real editor: it launches the helper as a local stdio server, and the helper forwards each call over loopback to the running application. In 2.0+ that also covers the Icon Explorer and the batch tools.

This guide is for IconVectors 2.0+ on Windows, where the helper is IconVectorsMcp.exe, on macOS, where it sits inside the app bundle, and on Linux; the catalog is exactly 166 tools on all three. On Linux the helper is at the path shown below, and the configuration works there too.

1. Start IconVectors

Windows (2.0+)

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

macOS (2.0+)

open -a /Applications/IconVectors.app

Linux (2.0+)

/usr/bin/IconVectors

Leave it running. Cursor starts the helper; you never start it yourself. The helper reaches the application on 127.0.0.1:61337 unless you changed Options/McpPort, and with two windows open only the instance that owns the port answers.

2. Create Cursor's MCP configuration

Put the server in .cursor/mcp.json for one project or in %USERPROFILE%\.cursor\mcp.json (~/.cursor/mcp.json on macOS and Linux) for everything. The command value is a JSON string that Cursor executes directly, not a shell fragment, so do not wrap it in cmd or powershell.

Windows example

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

macOS example

{
  "mcpServers": {
    "iconvectors": {
      "type": "stdio",
      "command": "/Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp",
      "args": ["--port", "61337"]
    }
  }
}

Linux example

{
  "mcpServers": {
    "iconvectors": {
      "type": "stdio",
      "command": "/usr/bin/IconVectorsMcp",
      "args": ["--port", "61337"]
    }
  }
}

Then open Cursor Settings -> Tools & MCP (some Cursor surfaces show it as Customize -> MCPs), enable the iconvectors server, and approve its tools as they come up. Reload the Cursor window only if it has not picked up the saved file.

3. Verify the connection

The Tools & MCP view shows whether the server is enabled and how many tools it discovered; 166 is the number to expect on 2.00. Then ask Cursor for the four discovery calls:

• Use the iconvectors MCP server to call app_ping and tell me whether the editor 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.

Follow with document_getInfo and selection_get in the Editor, or explorer_get_state in the Explorer. Do not start verification with Save As or an export; a read-only call proves the bridge just as well and cannot overwrite anything.

4. Install the instructions and the skill

Copy cursor-agent-instructions.template.md to the project root as AGENTS.md, or merge its short policy into the AGENTS.md you already have. If you prefer Cursor Rules, they live in .cursor/rules/*.mdc and need valid rule frontmatter; renaming a plain Markdown file to .mdc is not enough. Help -> Open MCP Files Folder in IconVectors opens the per-user MCP helper-files folder, the first place to look for the template and the skill.

Install the complete iconvectors-mcp skill, references directory included, at either location (the user equivalents under your home folder also work):

• .agents/skills/iconvectors-mcp/SKILL.md
• .cursor/skills/iconvectors-mcp/SKILL.md

The skill's references hold the tool schema. Point rules at the skill rather than copying the schema into every rule file.

5. Make a first bounded edit

1. Have Cursor inspect the workspace, the document, the selection, and whatever DOM or style state the change depends on.
2. Ask for one simple shape, or one change to the selected element.
3. Have it reinspect the result, and render a preview only when the numbers are not enough.
4. Save or export only when you named a destination.

Several related edits go in one history transaction (history_beginTransaction, the edits, then commit or roll back with the exact txId). An allowlist does not make Save As, export, document replacement or Explorer file operations undoable; those stay behind prompts.

Working with 166 tools

Cursor is naming-compatible with all 166 production tools under their canonical names, and it publishes no fixed tool-count or output ceiling. Exposure by task still helps the model choose: keep the discovery tools and enable the Editor, Explorer, Path, Paint, Export or Batch family the job needs. That selection is a Cursor setting; IconVectors serves the same catalog to every client and has no profiles of its own. Cursor 3.6 and later can review tool calls automatically and keep allowlists. Prefer bounded DOM and Explorer results, and skip full previews and base64 output unless you need them.

Since IconVectors 2.10 the catalog is 166 tools, and the eleven new ones are the Explorer's batch commands: all 14 of them are on the MCP surface, each as a plan request followed by an apply request, with the same preview counts, diagnostics and write safeguards as the desktop dialogs. The same client can therefore add badge overlays to a set, make Hot, Disabled and Dark Theme versions, export PNG and ICO files, convert a folder to currentColor or optimize its SVGs, as long as you read the plan before you approve the apply. The sequence is in Drive Icon Explorer and Batches from MCP.

Approvals and safety

Cursor asks for tool approval by default. Auto-review and allowlists are fine for calls you understand and that stay bounded. Keep prompting for document replacement, save and export, Explorer file operations, and batch apply; an allowlist is a client policy, not an Undo. After a structural edit, element ordinals can be stale, so have Cursor reinspect before it reuses one.

Troubleshooting

The server is missing or disabled

Validate the JSON and the scope (project file or user file), then look in Tools & MCP. Reload the window if Cursor has not picked up a saved change.

The executable or the bridge fails

Check the absolute Windows path, start IconVectors, and match the port. With several instances open, confirm identity with app_getInfo; the protocol has no instance selector.

You need logs

Open View -> Output (Ctrl+Shift+U) and choose MCP Logs.

Wrong state or stale navigation

Reinspect the workspace, document, selection or Explorer state. An Explorer navigation that returned status: "accepted" has started, not finished; wait for explorer_get_state to report the requested folder before the next operation.

A path, the catalog or the output fails

Use a native absolute Windows path with JSON escaping. Expose a task-focused subset and ask for bounded results.

A call times out

Distinguish Cursor's startup timeout from the helper's 10-second application-bridge timeout. Check MCP Logs and whether IconVectors is responsive before changing settings.

For current client controls, see the official Cursor MCP documentation.

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