Server data from the Official MCP Registry
Read and write a FreeVectorIcons design collection: briefs, DESIGN.md, icons and brand assets.
About
Read and write a FreeVectorIcons design collection: briefs, DESIGN.md, icons and brand assets.
Security Report
Valid MCP server (2 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
12 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: FVI_TOKEN
Environment variable: FVI_API_URL
Environment variable: FVI_READ_ONLY
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@freevectoricons/mcp@0.3.0-beta.3"
],
"env": {
"FVI_TOKEN": "your-fvi-token-here",
"FVI_API_URL": "your-fvi-api-url-here",
"FVI_READ_ONLY": "your-fvi-read-only-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
@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
- Open a collection at freevectoricons.com.
- Go to Integrations → Setup MCP.
- 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).
- Install from Cursor Marketplace once listed, or copy this repo to
~/.cursor/plugins/local/freevectoriconsfor local testing (copy files; avoid broken symlinks). - Open Plugins → Configure and set Collection token (
FVI_TOKEN) from FreeVectorIcons → Integrations → Setup MCP. - Optional:
FVI_API_URL(defaults to production),FVI_READ_ONLY=trueto 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
| Variable | Required | Default | Description |
|---|---|---|---|
FVI_TOKEN | yes | — | Collection-scoped MCP token (fvi_col_*). Collection binding is derived via GET /api/mcp/whoami. |
FVI_COLLECTION_ID | no | — | Deprecated / override only. If set and it disagrees with the token’s collection, the adapter fails closed (COLLECTION_MISMATCH). Prefer omitting it. |
FVI_API_URL | no | https://freevectoricons.com/api | API base URL (include /api) |
FVI_READ_ONLY | no | false | When true, write tools are not registered. Can only narrow token scopes |
FVI_TOOLS | no | — | Comma-separated tool names to register. Old names from before 0.3.0-beta.3 are accepted. Can only narrow access |
FVI_SKIP_TOKEN_CHECK | no | false | Escape hatch if a future token shape is rejected locally |
FVI_ALLOW_FILE_PATHS | no | false | Allow filePath on upload tools. Off by default |
FVI_FILE_PATH_ROOTS | no | — | Comma-separated directories filePath may read |
FVI_TIMEOUT_MS | no | 30000 | HTTP request timeout for API calls (milliseconds) |
FVI_UPLOAD_TIMEOUT_MS | no | 120000 | Timeout for binary upload requests (milliseconds) |
FVI_RETRY_MAX | no | 3 | Maximum retry attempts for transient failures |
FVI_RETRY_BASE_MS | no | 500 | Base delay for exponential backoff (milliseconds) |
FVI_LOG_LEVEL | no | info | Log level: debug, info, warn, or error (stderr, JSON) |
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=trueif 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.
- Mint a token for the target collection in Setup MCP.
- Re-Add / Configure the connector env with the new
FVI_TOKEN(uninstall + add if Configure is unavailable). - Smoke
get_collection_contextand confirmcollection.id/name. - 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
| Tool | Description |
|---|---|
get_collection_context | Collection metadata, strategy brief, asset summary |
list_collection_assets | All assets (metadata only) |
search_collection_assets | Search by name, tag, category, or style |
get_asset | One asset by ID |
get_asset_content | Inline UTF-8 for catalog SVGs, uploaded SVGs, Markdown |
get_asset_download_url | Short-lived URL for PNG, PDF, spreadsheets (XLS/XLSX), and other binaries |
get_asset_download_urls | The same URLs for up to 50 assets per call |
get_asset_spreadsheet_preview | Size-capped first-sheet CSV/HTML preview for XLS/XLSX |
list_asset_versions | Version number, name, size, verified hash, and source |
list_community_packs | Public community icon packs with license and agentGuide URLs |
get_community_pack_guide | A pack's AGENTS.md: license, attribution, URL patterns, curated usage guide |
Write
| Tool | Description |
|---|---|
create_asset_upload | Create asset record and signed upload target |
park_asset | Upload inline text or base64 into the collection |
create_asset_version | Upload a new version of an existing asset (prior versions retained) |
set_collection_strategy_brief | Replace collection.metadata.strategyBrief (native Strategy Brief tab) |
promote_asset_to_strategy_brief | Copy Markdown asset text into the native brief (does not delete the asset) |
set_asset_transcription_status | Patch textLayer / transcription metadata (no OCR) |
update_asset | Metadata-only PATCH: name, tags, documentType, DRL fields, custom metadata, and links |
set_collection_design_md | Pin the canonical DESIGN.md from inline Markdown or an existing asset |
update_collection_purpose | Set collection purpose to brand or records |
create_asset_version_upload | Signed upload for a new version of an existing asset |
complete_asset_upload | Verify checksum and size, then make that version current |
refresh_asset_upload | Issue a fresh upload URL for a pending upload whose URL expired (15 minutes) |
revert_asset_to_version | Copy an earlier version forward. History is kept |
delete_collection_asset | Soft-unlink collection item only — does not hard-delete bytes. Requires the delete scope |
probe_asset_text_layer | Best-effort PDF embedded text probe (API feature-flagged) |
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.
| Old name | New name |
|---|---|
complete_design_asset_upload | complete_asset_upload |
create_design_asset_upload | create_asset_upload |
create_design_asset_version | create_asset_version |
create_design_asset_version_upload | create_asset_version_upload |
delete_design_collection_asset | delete_collection_asset |
get_design_asset | get_asset |
get_design_asset_content | get_asset_content |
get_design_asset_download_url | get_asset_download_url |
get_design_asset_download_urls | get_asset_download_urls |
get_design_asset_spreadsheet_preview | get_asset_spreadsheet_preview |
get_design_collection_context | get_collection_context |
list_design_asset_versions | list_asset_versions |
list_design_collection_assets | list_collection_assets |
park_design_asset | park_asset |
probe_design_asset_text_layer | probe_asset_text_layer |
promote_design_asset_to_strategy_brief | promote_asset_to_strategy_brief |
refresh_design_asset_upload | refresh_asset_upload |
revert_design_asset_to_version | revert_asset_to_version |
search_design_collection_assets | search_collection_assets |
update_design_asset | update_asset |
update_design_asset_transcription_status | set_asset_transcription_status |
update_design_collection_purpose | update_collection_purpose |
update_design_collection_strategy_brief | set_collection_strategy_brief |
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_layerdetects embedded PDF text only when enabled on the API; handwritten/scanned pages often have no usable text layer. Failures settranscription.status=failedwithout deleting the asset. - Soft unlink, not hard delete.
delete_collection_assetremoves 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.
Reviews
No reviews yet
Be the first to review this server!
More AI & ML MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Lharries · Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions