FreeVectorIcons

@freevectoricons/mcp

Beta. This package is under active development. Tool schemas, configuration options, and error behavior may change before v1.0.0. Report issues or review the product docs before production use.

Model Context Protocol (MCP) server for FreeVectorIcons design collections.

Connects Cursor, Claude Desktop, and other MCP clients to a single FreeVectorIcons collection (token-derived binding — configure FVI_TOKEN only): catalog icons, uploaded SVGs, strategy briefs, DESIGN.md, and related project files. Access is scoped to one collection token.

npm: @freevectoricons/mcp

Overview

Agents that generate icons inline often produce inconsistent SVG, unstable identifiers, and incorrect licensing across sessions. FreeVectorIcons stores approved assets in versioned collections with stable IDs and metadata.

This server exposes that collection to MCP clients. Agents search and retrieve canonical assets instead of regenerating SVG from scratch, and write designs back into the collection for review. Uploaded assets are versioned, so agents can iterate freely without losing prior work. The server runs over stdio and calls the FreeVectorIcons HTTP API. Responses are metadata-first JSON; file bytes are fetched only when a tool requests inline content or a download URL.

Hosted connector. If your client supports remote MCP servers, you can skip this package and connect to https://mcp.freevectoricons.com/mcp instead: nothing to install, and you sign in from your client or send a collection token as an Authorization: Bearer header. See freevectoricons.com/mcp. This package suits agents that upload files straight from disk, or setups that prefer a local process.

Requirements

• Node.js 20 or later
• A FreeVectorIcons account
• A collection-scoped MCP token

Setup

1. Open a collection at freevectoricons.com.
2. Go to Integrations → Setup MCP.
3. Create a collection-scoped token and copy the secret. The collection id is derived from the token (no separate collection id env var required).

Add the server to your MCP client configuration (for example .cursor/mcp.json):

{  "mcpServers": {    "freevectoricons": {      "command": "npx",      "args": ["-y", "@freevectoricons/mcp"],      "env": {        "FVI_TOKEN": "<collection-token>"      }    }  }}

Run the server with npx as shown above. MCP uses stdio for protocol messages; the process must not write non-protocol output to stdout.

See mcp.json.example for a copy-paste template.

Claude Desktop

Add the same mcpServers block to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor Marketplace (plugin)

This repository is also a Cursor Plugin (.cursor-plugin/plugin.json + mcp.json).

1. Install from Cursor Marketplace once listed, or copy this repo to ~/.cursor/plugins/local/freevectoricons for local testing (copy files; avoid broken symlinks).
2. Open Plugins → Configure and set Collection token (FVI_TOKEN) from FreeVectorIcons → Integrations → Setup MCP.
3. Optional: FVI_API_URL (defaults to production), FVI_READ_ONLY=true to hide write tools.

Submit / re-index: cursor.com/marketplace/publish.

Google Antigravity and Gemini CLI

Gemini CLI passed the compatibility tests against the hosted endpoint on 5 Nov 2026. Antigravity is still being tested after the 0.3.0-beta.3 tool rename; until it passes, treat it as a preview and report issues.

Antigravity plugin. This repository is also an Antigravity plugin (.antigravity-plugin/plugin.json, mcp_config.json and the skills/ folder). Install it, then turn it on under /plugin (CLI) or Settings → Customizations (app) and paste your collection token when asked.

Antigravity config block. Or add this to ~/.gemini/config/mcp_config.json (all projects) or .agents/mcp_config.json (one workspace):

{  "mcpServers": {    "freevectoricons": {      "command": "npx",      "args": ["-y", "@freevectoricons/mcp"],      "env": {        "FVI_TOKEN": "<collection-token>"      }    }  }}

Gemini CLI extension. Install from this repository and enter your collection token when prompted:

gemini extensions install https://github.com/FreeVectorIcons/fvi-mcp

Change the token later with gemini extensions config freevectoricons. The extension pins a released package version, so a new release reaches you when you run gemini extensions update freevectoricons.

Environment variables

Set FVI_API_URL only when pointing at a non-production API.

Write tools are enabled by default. Agents can park new assets and upload new versions of existing ones; each change is stored as a version you can review or restore in the collection UI. Set FVI_READ_ONLY=true only if you want retrieval without uploads.

Token security

Treat FVI_TOKEN like a password. It grants access to one collection.

• Prefer OS keychain integration or a secrets manager in team environments.
• If you use environment variables in config files, restrict file permissions and never commit tokens to version control.
• Rotate tokens from the collection Integrations tab if a token may have been exposed.
• Set FVI_READ_ONLY=true if an agent should only read from the collection, not upload.

Switching collections (token rebind)

Restarting MCP servers alone does not rebind a shared stdio connector that still has an old FVI_TOKEN.

1. Mint a token for the target collection in Setup MCP.
2. Re-Add / Configure the connector env with the new FVI_TOKEN (uninstall + add if Configure is unavailable).
3. Smoke get_collection_context and confirm collection.id / name.
4. Use a second named server entry when two collections must stay connected in parallel.

Tools

Records tools (get_asset_spreadsheet_preview, set_collection_strategy_brief, promote_asset_to_strategy_brief, set_asset_transcription_status, delete_collection_asset, probe_asset_text_layer) are listed only when the API has those features enabled. Write tools are also hidden when FVI_READ_ONLY=true or the token lacks write scope.

Read

Write

Uploaded assets keep version history in FreeVectorIcons. Agents should prefer create_asset_version when refining an existing design, and park_asset for new files. Agents should use metadata and download URLs for images, PDFs, and spreadsheets (.xls / .xlsx) — workbook bytes are not dumped into MCP tool results. Use get_asset_spreadsheet_preview for a capped first-sheet look. For scanned PDFs, set transcription status after parking a Markdown sibling.

Parked STRATEGY_BRIEF.md is a supporting document only — it does not fill the native Strategy Brief tab until you call promote_asset_to_strategy_brief or set_collection_strategy_brief.

Optional write metadata: drlProjectId, drlAssetType, documentType, tags.

Renamed tools (0.3.0-beta.3)

Tool names dropped the redundant design_ so they fit clients that prefix tool names with the server name (Antigravity's prefix is 33 characters, and Gemini allows 64 in total). Arguments, scopes and behaviour are unchanged. Results are unchanged except that a set_collection_strategy_brief dry run now reports would.operation: "set_collection_strategy_brief".

The old names still work when called, on this package and on the hosted endpoint, but are no longer listed. Update saved prompts, tool allowlists (FVI_TOOLS accepts either) and cached approvals to the new names, then reconnect or restart your client so it reloads the tool list. Old names will be removed in a later release, announced here first.

set_asset_transcription_status still only records status metadata and does not run OCR.

Limitations

• Collection-scoped. One token grants access to one collection, not the global icon catalog.
• Catalog quality. Catalog SVGs are AI-generated and refined on a schedule; verify assets before production use.
• No design review. The server moves files and metadata; it does not evaluate brand fit.
• OCR is best-effort. probe_asset_text_layer detects embedded PDF text only when enabled on the API; handwritten/scanned pages often have no usable text layer. Failures set transcription.status=failed without deleting the asset.
• Soft unlink, not hard delete. delete_collection_asset removes the collection membership only — storage bytes stay until a future hard-delete policy.

Development

Building, testing and releasing this package are covered in CONTRIBUTING.md.

Related

• @freevectoricons/mcp package architecture — Solution Design Architecture (stdio transport, tool mapping, security boundary)
• Keeping @freevectoricons/mcp vulnerability-free — empty published dependencies, audit gates, Dependabot
• freevectoricons.com/mcp — product documentation
• ai-icon-generator — open pipeline for catalog icons

License

MIT — applies to this MCP server software only. See LICENSE.

Icon usage is governed separately by the FreeVectorIcons Community License. Attribution may be required depending on your plan and how icons are used.