# pictogrammers-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant **search, download and use [Pictogrammers](https://pictogrammers.com) icons** (Material Design Icons, MDI Light, Memory) instead of hand-writing SVG — while keeping every icon in a project **visually coherent** by pinning it to a single library and variant.

## Why

Hand-drawn SVG icons are inconsistent and often wrong. This server gives the model a real icon set of 8,000+ professionally designed glyphs, ranked search, and multiple output formats (raw SVG, JSX, `@mdi/react`, `@mdi/js` constants, data URIs). A `pictogrammers.config.json` at the project root pins **one** library so the model can't silently mix styles — if it tries, it gets a coherence warning.

## Libraries

| id | name | grid | count | style |
|------|------|------|-------|-------|
| `mdi` | Material Design Icons | 24×24 | ~7,400 | Bold filled; most icons have an `-outline` twin |
| `mdil` | MDI Light | 24×24 | ~260 | Thin single-weight line icons |
| `memory` | Memory Icons | 22×22 | ~650 | Pixel-precise, for low-res/embedded displays |

Data comes from the official `pictogrammers.com/data/*.json` files, cached to disk on first use — after that the server works offline.

## Install & build

```bash
npm install
npm run build
```

## Register with Claude Code

Add to your `.mcp.json` (project) or user MCP config. See `mcp.example.json`:

```json
{
  "mcpServers": {
    "pictogrammers": {
      "command": "node",
      "args": ["F:/_projects/dru/pictogrammers-mcp/dist/index.js"],
      "env": {
        "PICTOGRAMMERS_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}
```

Or from the CLI:

```bash
claude mcp add pictogrammers -- node F:/_projects/dru/pictogrammers-mcp/dist/index.js
```

## Tools

| tool | purpose |
|------|---------|
| `init_project_icons` | Pin the project to **one** library + variant (writes `pictogrammers.config.json`). Call this first. |
| `project_icon_status` | Show the pinned library, defaults, and inventory of icons used. |
| `list_libraries` | List libraries with counts, grid sizes and npm packages. |
| `list_tags` | Browse the category tags of a library. |
| `search_icons` | Ranked keyword search; defaults to the pinned library/variant. |
| `get_icon` | Fetch one icon as `svg` / `svg-path` / `jsx` / `react-mdi` / `js-constant` / `data-uri`. |
| `download_icons` | Write `.svg` files (or a JSON map) to a directory. |

### Typical flow

1. `init_project_icons { "library": "mdi", "variant": "outline" }`
2. `search_icons { "query": "shopping cart" }` → pick `cart-outline`
3. `get_icon { "name": "cart-outline", "format": "jsx" }` → paste into a component
4. …or `download_icons { "names": ["cart-outline","account-outline"], "outputDir": "src/assets/icons" }`

Because the project is pinned, every later `search_icons`/`get_icon` stays within the same family, and requesting another library returns a visible coherence warning.

## Configuration (env)

| var | default | meaning |
|-----|---------|---------|
| `PICTOGRAMMERS_PROJECT_DIR` | server cwd | where `pictogrammers.config.json` lives |
| `PICTOGRAMMERS_CACHE_DIR` | `~/.pictogrammers-mcp/cache` | downloaded data cache |
| `PICTOGRAMMERS_BASE_URL` | `https://pictogrammers.com/data` | data source |

## License

MIT. Icon data is © the Pictogrammers project under their respective licenses (MDI/MDIL: Apache-2.0; see pictogrammers.com/docs).