MCP 服务器

fvi-mcp

MCP server for FreeVectorIcons design collections, enabling agents to search and fetch approved icons and assets instead of generating SVG from scratch.

README

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.

Setup

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

Open a collection at freevectoricons.com
Integrations → Setup MCP
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

Variable	Required	Default	Description
`FVI_TOKEN`	yes	—	Collection-scoped MCP token
`FVI_COLLECTION_ID`	yes	—	Collection id
`FVI_API_URL`	no	`http://localhost:5001/api`	API base URL (include `/api`)

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

Tools

Read

Tool	What it does
`get_design_collection_context`	Collection metadata, strategy brief, asset summary
`list_design_collection_assets`	All assets (metadata only)
`search_design_collection_assets`	Search by name, tag, category, or style
`get_design_asset`	One asset by id
`get_design_asset_content`	Inline UTF-8 for catalog SVGs, uploaded SVGs, Markdown
`get_design_asset_download_url`	Short-lived URL for PNG, PDF, and other binaries

Write

Tool	What it does
`create_design_asset_upload`	Create asset record + signed upload target
`park_design_asset`	Upload inline text or base64 into the collection
`create_design_asset_version`	Upload a new version of an existing asset

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.