fvi-mcp

MCP server for FreeVectorIcons design collections.

Connects Cursor, Claude Desktop, and other MCP clients to one FVI collection — icons, uploaded SVGs, strategy briefs, DESIGN.md, and related project files. Scoped to a single collection token.

npm: @freevectoricons/mcp

Why this exists

The usual agent workflow for icons is: prompt → inline SVG → paste into code. That breaks down quickly — inconsistent paths, missing viewBox, made-up attribution, different output on every retry.

FVI stores assets in a collection with stable ids, tags, and license fields. This server lets agents search and fetch what's already approved instead of generating new SVG from scratch.

It's a stdio MCP wrapper over the FVI HTTP API. Responses are metadata-first JSON; file bytes are fetched only when a tool asks for content or a download URL.

Related MCP server: RemixIcon MCP

Setup

You need a FreeVectorIcons account and an MCP token for a design collection.

1. Open a collection at freevectoricons.com

2. Integrations → Setup MCP

3. Create a token; copy the collection ID and secret

Add to .cursor/mcp.json (or your client's MCP config):

{
  "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>"
      }
    }
  }
}

Use npx, not pnpm run. Package managers print lifecycle text to stdout, which breaks MCP stdio transport.

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

Environment variables

For production: FVI_API_URL=https://freevectoricons.com/api

Tools

Read

Write

Binary files are not embedded in MCP responses. Agents should use metadata + download URLs for images and PDFs.

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

Development

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

To run from a local checkout in Cursor:

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

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

What this is not

• Not a global icon search API. One token, one collection.

• Not a guarantee of pixel-perfect icons. Catalog SVGs are AI-generated and refined on a schedule; check assets before production use.

• Not a replacement for your design review. It moves files and metadata; it doesn't judge brand fit.

Related

• freevectoricons.com/mcp — product docs

• ai-icon-generator — open pipeline that produces catalog icons

License

MIT — see LICENSE.