# 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](https://iconify.design) 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](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

```sh
docker build -t icon-search-mcp .
```

Then register it with your MCP client:

```json
{
  "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`.

```json
{
  "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

```sh
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.