icon-search-mcp

An MCP server that finds open-source, commercially-usable icons and returns direct SVG download links. Runs locally in Docker over stdio.

Icons come from the Iconify public API — 300,000+ icons across 231 open-source icon sets, each with machine-readable SPDX licence metadata.

Design rationale, recorded decisions, and known limitations live in docs/design.md.

How it works

Iconify's search index is keyword-based, not semantic — ?query=fast deployment returns zero results. So the natural-language step lives in the calling model, not in this server:

User: "find me an icon that represents fast deployment"
  │
  ▼  the host model translates the description into keywords
search_icons({ keywords: ["rocket", "deploy", "upload"] })
  │
  ├─ one parallel Iconify query per keyword
  ├─ merge and dedupe, tracking which keywords each icon matched
  ├─ drop icons whose set fails the licence policy
  └─ rank: most keywords matched first, then Iconify's relevance order

The tool description instructs the host model to do that translation and to retry with broader keywords when a search comes back empty.

Setup

docker build -t icon-search-mcp .

Then register it with your MCP client:

{
  "mcpServers": {
    "icon-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "icon-search-mcp"]
    }
  }
}

For Claude Code: claude mcp add icon-search -- docker run --rm -i icon-search-mcp

Tool: search_icons

Parameter	Type	Default	Description
keywords	string[] (1–5)	required	Concrete English icon keywords, most relevant first
limit	number (1–64)	12	Maximum icons to return
license_policy	enum	permissive	See below

Each result carries the icon id, set name, author, full licence details, and both a download_url (serves Content-Disposition: attachment) and a preview_url.

{
  "id": "material-symbols:rocket-launch",
  "name": "rocket-launch",
  "set": "Material Symbols",
  "author": { "name": "Google", "url": "https://github.com/google/material-design-icons" },
  "license": {
    "spdx": "Apache-2.0",
    "title": "Apache 2.0",
    "url": "https://github.com/google/material-design-icons/blob/master/LICENSE",
    "attribution_required": false,
    "copyleft": false
  },
  "download_url": "https://api.iconify.design/material-symbols/rocket-launch.svg?download=1",
  "preview_url": "https://api.iconify.design/material-symbols/rocket-launch.svg",
  "matched_keywords": ["rocket", "launch"]
}

Licence policies

Policy	Allows	Reach
permissive (default)	MIT, Apache-2.0, ISC, BSD-3-Clause, CC0-1.0, Unlicense, OFL-1.1, MPL-2.0	~224k icons
permissive_plus_attribution	above + CC-BY-4.0, CC-BY-3.0 — you must credit the author	~291k icons
all	above + copyleft (GPL-*, CC-BY-SA-*) — share-alike terms apply to derivatives	~315k icons

NonCommercial sets (cbi, ps) are excluded under every policy, including all.

Licence data is reported as published by each icon set; verify it against the linked LICENSE file before shipping an icon in a product. This server surfaces licence terms, it does not give legal advice.

Development

npm install
npm test    # builds, then runs offline unit tests against fixtures
npm start   # run the server directly on stdio, without Docker

src/licenses.ts and src/search.ts are pure functions with no I/O; src/iconify.ts is the only module that touches the network.