@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.

... View full README on GitHub