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

Related MCP server: RemixIcon MCP

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 token and copy the collection ID and secret.

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

{
  "mcpServers": {
    "freevectoricons": {
      "command": "npx",
      "args": ["-y", "@freevectoricons/mcp"],
      "env": {
        "FVI_API_URL": "https://freevectoricons.com/api",
        "FVI_COLLECTION_ID": "<collection-id>",
        "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.

macOS (Claude Desktop)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the same mcpServers block.

Windows (Claude Desktop)

Edit %APPDATA%\Claude\claude_desktop_config.json and add the same mcpServers block.

Linux (Claude Desktop)

Edit ~/.config/Claude/claude_desktop_config.json and add the same mcpServers block.

Environment variables

FVI_API_URL can be omitted if you use the production API. The setup example above sets it explicitly for clarity.

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.

Tools

Read (always available)

Write (enabled by default)

Uploaded assets keep version history in FreeVectorIcons. Agents should prefer create_design_asset_version when refining an existing design, and park_design_asset for new files. Agents should use metadata and download URLs for images and PDFs.

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

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.

Development

For local API development against a running FVI API server:

FVI_API_URL=http://localhost:5001/api \
FVI_COLLECTION_ID=<collection-id> \
FVI_TOKEN=<collection-token> \
node dist/mcp-server.mjs

npm install
npm run build
node dist/mcp-server.mjs

To run from a local checkout:

"args": ["-y", "file:/absolute/path/to/fvi-mcp"]

Build first (npm run build). The bundled entry is dist/mcp-server.mjs.

Related

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