pictogrammers-mcp

An MCP server that lets an AI assistant search, download and use Pictogrammers 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

npm install
npm run build

Register with Claude Code

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

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

Or from the CLI:

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).