Svg/icons MCP

Svg/icons MCP

The Svg/icons MCP server connects AI coding tools to svgicons.com, a catalog of 320K+ open-source SVG icons. Assistants can search icons and icon sets, fetch icon metadata, and get icon recommendations for a UI without any account. With a Pro account (OAuth or a scoped API token), they can also fetch raw SVG markup, render PNG exports, and create, read, extend, and export persistent Icon Collections — including custom-styled icons — so the icon-discovery step never leaves the development workflow.

The server is hosted, remote MCP over Streamable HTTP (JSON-RPC requests via HTTP POST). There is no local install and no local Svg/icons MCP server package.

Endpoint:

https://svgicons.com/mcp

Current MCP server version: 0.3.2 (protocol 2025-06-18).

Official MCP Registry name: com.svgicons/mcp — see [Official MCP Registry listing](#official-mcp-registry-listing).

What This Repo Contains

This repository documents the hosted MCP endpoint. It contains no server code.

• Client connection instructions and reference configs
• Live tool reference
• Authentication and scope guidance
• Prompting guidance and a prompt library
• Example workflow documentation
• Security guidance and troubleshooting
• Relationship to the REST API and CLI repos
• Community use case templates

The live product docs are the source of truth: MCP server docs and the MCP developer overview.

Live MCP Tools

The hosted endpoint exposes exactly these 12 live tools.

Search and read (anonymous metadata; raw SVG with Pro):

• search_icons — search icon metadata by query, category, or icon set prefix; add includeSvg for raw SVG with a Pro token.
• search_icon_sets — search icon sets by name, prefix, author, category, or description to pick a consistent visual family.
• get_icon — fetch one icon by ID; metadata is public, raw SVG requires a Pro token.

Recommendations (anonymous):

• recommend_icons_for_ui — describe a UI or screen and receive icon candidates with short rationales.

Icon Collections — create, read, extend (Pro):

• create_icon_kit — create a persistent Icon Collection and optionally seed it with icon IDs.
• generate_icon_kit_for_project — generate an Icon Collection from a project brief, screen list, or required concepts.
• list_icon_collections — list your Icon Collections with icon counts, an optional name/slug filter, and pagination.
• get_icon_collection — read one collection with paginated entries, including custom-icon entries and their customized SVG bodies.
• add_icons_to_collection — add catalog icons to an existing collection; idempotent, already-present icons are skipped.
• remove_icon_from_collection — remove an icon from a collection; entry-precise by default, pass allVariants: true to remove every entry of the icon.

Exports (Pro):

• export_icon_png — render one icon as a PNG file or a ZIP of PNG variants, returned as a JSON-safe base64 payload.
• export_icon_collection — queue an Icon Collection export: SVG folders, SVG sprites, React/Vue/Svelte/Solid/Blade components, Storybook galleries, npm package scaffolds, PNG packs, Iconify JSON, and JSON/license manifests.

See [docs/TOOLS.md](docs/TOOLS.md) for verified input fields, output notes, access requirements, and safe prompt examples.

Export behavior worth knowing

• Custom-icon entries in a collection export their customized snapshot under a unique derived filename — the customization is kept, not replaced by the catalog icon.
• When you do not pass colorPolicy, collections that carry styling (an applied style or custom-icon entries) default to preserve, so exported files keep the colors the customization defined. Plain collections keep the currentColor default. An explicit colorPolicy always wins.
• Use formats: ["png"] as a shorthand for png-pack.

Access Tiers And Authentication

Anonymous (no account): metadata-only access to search_icons, search_icon_sets, get_icon, and recommend_icons_for_ui. Anonymous requests are rate-limited per method and currently capped at 10 icons per search or recommendation. Raw SVG, PNG export, and all Icon Collection tools are not available anonymously.

Pro: authenticate with either of:

• OAuth 2.0 — authorization code with PKCE and Dynamic Client Registration. Clients discover the configuration at https://svgicons.com/.well-known/oauth-authorization-server (resource metadata at /.well-known/oauth-protected-resource/mcp), register dynamically, and send you to svgicons.com to sign in and approve access.
• Pro API token — a scoped personal access token created from your account page, sent as Authorization: Bearer YOUR_API_TOKEN in clients that support private headers.

Pro raises search caps (up to 50 icons per search) and unlocks raw SVG, PNG export, and the Icon Collection and export tools.

Token scopes — give each client the smallest set it needs:

The Pro Plan is €6/$7 per month or €69/$79 lifetime — see pricing. On the website, Icon Collections are also available to free Member accounts through a one-time trial allowance of 15 Pro credits; MCP and API access always require a Pro token.

See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) and the MCP server docs.

Connect Your Client

Claude Code

claude mcp add --transport http svgicons https://svgicons.com/mcp

Then run /mcp inside Claude Code to complete the OAuth sign-in. To use a Pro API token instead:

claude mcp add --transport http svgicons https://svgicons.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Claude.ai and Claude Desktop (custom connector)

1. Open Customize → Connectors and click Add custom connector.
2. Enter https://svgicons.com/mcp and click Add.
3. Complete the OAuth prompt to sign in to svgicons.com (Dynamic Client Registration — no client ID needed).
4. Enable the connector per conversation from the + menu → Connectors.

Team/Enterprise owners add it under Organization settings → Connectors → Add → Custom → Web; members then connect individually.

Cursor

Project .cursor/mcp.json or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "svgicons": {
      "url": "https://svgicons.com/mcp"
    }
  }
}

Omit headers to use Cursor's OAuth flow, or add a token:

{
  "mcpServers": {
    "svgicons": {
      "url": "https://svgicons.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "svgicons": {
      "serverUrl": "https://svgicons.com/mcp"
    }
  }
}

Omit headers for OAuth, or reference an environment variable:

{
  "mcpServers": {
    "svgicons": {
      "serverUrl": "https://svgicons.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SVGICONS_API_TOKEN}"
      }
    }
  }
}

VS Code (GitHub Copilot agent mode)

Workspace .vscode/mcp.json:

{
  "servers": {
    "svgicons": {
      "type": "http",
      "url": "https://svgicons.com/mcp"
    }
  }
}

ChatGPT and Codex

ChatGPT authenticates through OAuth with Dynamic Client Registration; Codex-style clients can use a bearer token. Follow the website guide: Use MCP with ChatGPT and Codex, plus [configs/chatgpt-codex.md](configs/chatgpt-codex.md) and [configs/codex.example.md](configs/codex.example.md).

Other clients

Clients that support remote HTTP MCP servers can connect with the generic shape:

{
  "mcpServers": {
    "svgicons": {
      "type": "http",
      "url": "https://svgicons.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Clients that only launch local command-based MCP servers can bridge with mcp-remote:

{
  "mcpServers": {
    "svgicons": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://svgicons.com/mcp",
        "--header",
        "Authorization: Bearer ${SVGICONS_API_TOKEN}"
      ],
      "env": {
        "SVGICONS_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

More client guidance: [docs/CLIENTS.md](docs/CLIENTS.md) and [configs/README.md](configs/README.md).

Official MCP Registry Listing

The server is published in the Official MCP Registry as com.svgicons/mcp. Verify the live listing:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.svgicons"

Directories that ingest the official registry (such as PulseMCP) pick the listing up automatically.

Example Agent Prompts

1. "Find me a minimal lock icon that works at 16px and add it to my app's Icon Collection."
2. "Recommend icons for a billing settings page — I need payment method, invoice, and refund concepts — then create a collection called 'Billing UI' with the best ones."
3. "Export my 'Dashboard' collection as React TypeScript components with a 20px default size and download the PNG pack at 2x density."

The [prompt library](prompts/README.md) includes copyable workflows for search, React components, dashboard navigation, emoji replacement, accessibility review, themeable icons, design-system review, Icon Collections, and PNG export. Start with [search icons](prompts/search-icons.md), then move to code or export prompts only after reviewing the tool calls and selected icons.

Examples And Use Cases

• [Examples](examples/README.md) show practical hosted MCP workflows. They are documentation examples, not runnable local MCP server apps.
• [Community use cases](use-cases/README.md) explain how to share workflows safely.
• [Use-case template](use-cases/TEMPLATE.md) provides a reusable submission format.
• [GitHub issue templates](.github/ISSUE_TEMPLATE/) support use cases, setup help, feedback, and bug reports.

Sample use cases are marked as examples, not real customer submissions. Review generated SVG and code before committing changes.

Validation

Run local checks before proposing changes:

npm ci
npm run validate

CI runs the same validation without live MCP calls, auth tokens, publishing, or deployment.

Related Repos And Docs

• Website MCP developer page: <https://svgicons.com/developers/mcp>
• MCP server docs: <https://svgicons.com/docs/mcp-server>
• ChatGPT and Codex setup docs: <https://svgicons.com/docs/chatgpt-codex-mcp-setup>
• REST API repo: <https://github.com/svgicons-com/api>
• CLI repo: <https://github.com/svgicons-com/cli>

Repo roles:

• MCP repo: AI coding tool workflows, hosted MCP setup, prompts, examples, security notes, and troubleshooting.
• API repo: REST API, OpenAPI, SDK, examples, and direct programmatic integration.
• CLI repo: terminal workflows, export automation, and project commands.

See [docs/API_RELATIONSHIP.md](docs/API_RELATIONSHIP.md).

Security Summary

• Do not paste tokens into public prompts, issues, screenshots, commits, or repos.
• Use OAuth where supported by the MCP client.
• Use bearer tokens only in supported clients and keep them private.
• Give every client the smallest scope set it needs and revoke unused tokens.
• Review tool calls before approval.
• Review AI-generated SVG and code before committing.
• Treat SVG insertion as code and content insertion.

See [SECURITY.md](SECURITY.md) and [docs/SECURITY.md](docs/SECURITY.md).

Start Here

• [Authentication](docs/AUTHENTICATION.md)
• [Tools](docs/TOOLS.md)
• [Client setup overview](docs/CLIENTS.md)
• [Config examples](configs/README.md)
• [Troubleshooting](docs/TROUBLESHOOTING.md)
• [API relationship](docs/API_RELATIONSHIP.md)
• [MCP security](docs/SECURITY.md)
• [Prompting guide](docs/PROMPTING_GUIDE.md)
• [Prompt library](prompts/README.md)
• [Examples](examples/README.md)
• [Community use cases](use-cases/README.md)