English Français العربية

io.github.asr-aditya/iconserve

Official registry Search and web

Icons for agentic development: search & fetch 366,000+ open-source icons as SVG/PNG. No API key.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http iconserve 'https://icons-for-agents.site/mcp'
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "iconserve": {
            "type": "http",
            "url": "https://icons-for-agents.site/mcp"
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. IconServe
  2. How an agent uses it
  3. Architecture
  4. Local development
  5. Deploy (Cloudflare free tier)
  6. Adding / updating icon sets
  7. Licensing

IconServe

A free, agent-readable service that aggregates 10,000+ open-source icons — Lucide, Heroicons, Tabler, and Simple Icons — and serves them as SVG or PNG at predictable URLs, with keyword + semantic search, an llms.txt, and an MCP server.

Runs entirely within the Cloudflare free tier (Workers + R2 + Workers AI).

How an agent uses it

NeedDo this
Embed an icon you know the name ofGET /i/{name}.svg (best match) or /icons/{set}/{name}.svg
Find the right iconGET /api/search?q=shopping+cart → names + ready URLs
Read the whole API in one shotGET /llms.txt (or /llms-full.txt)
Native tool callsMCP server at /mcp (search_icons, get_icon, list_sets)
OpenAPIGET /openapi.json
Discoverability surfaces (for crawling/browsing agents)
  • GET /icon/{set}/{name} — crawlable HTML page per icon (preview, usage, JSON-LD ImageObject + breadcrumb). /icon/{name} 302-redirects to the best match.
  • GET /sitemap.xml — every icon page (~10k URLs).
  • GET /robots.txt — explicitly allows AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, …) and points to the sitemap.
  • Landing page carries WebSite+SearchAction and WebAPI JSON-LD and Open Graph tags.
  • IndexNow: key file served at /{INDEXNOW_KEY}.txt; npm run indexnow pings Bing/Yandex to crawl new or changed URLs instantly (pass paths to submit a subset, e.g. npm run indexnow /icon/lucide/house).
Transforms (query params on any icon URL)
  • color= hex / CSS color / currentColor — e.g. ?color=%23e11d48
  • size= 1..2048 px
  • stroke= 0..20 (line icons)
  • style= e.g. solid (Heroicons), filled (Tabler)
  • format= svg | png

Example: /i/shopping-cart.svg?color=crimson&size=48&stroke=1.5

Architecture

Build (offline, on your machine — no Cloudflare cost)
  scripts/ingest.mjs  → data/pack/icons.json  (id → normalized SVG, currentColor-driven)
                        data/pack/catalog.json (names, tags, aliases, license, styles)
                        data/pack/corpus.json  (search text per icon)
  scripts/embed.mjs   → data/pack/embeddings.bin  (10k × 384, bge-small-en-v1.5)
                        data/pack/embed-index.json

Cloudflare
  R2 (ICONS)   holds the 4 packed artifacts; loaded once per isolate into memory
  Workers AI   embeds ONLY the query string at search time (same 384-dim model)
  Worker       routing, color/size/stroke transforms, PNG (resvg-wasm), search, MCP, docs
  Assets       public/index.html landing page

Semantic search = keyword ranking fused (reciprocal-rank fusion) with cosine similarity over the in-memory embeddings. No Vectorize, no per-vector billing, no dimension cap. If embeddings.bin is absent, search gracefully falls back to keyword-only.

Local development

npm install
npm run build:data     # ingest + embed  (embed downloads a ~40MB model once)
npm run upload:r2      # push artifacts into the LOCAL R2 store
npm run dev            # http://localhost:8787

In wrangler dev --local the Workers AI binding is offline, so search runs keyword-only locally. Semantic search activates once deployed (or when running against the remote AI binding).

Deploy (Cloudflare free tier)

wrangler login         # one-time, opens a browser
npm run deploy         # creates the R2 bucket, uploads artifacts, deploys the Worker

npm run deploy runs scripts/deploy.mjs: it creates the iconserve-icons bucket (idempotent), uploads the four artifacts to remote R2, then wrangler deploy.

Adding / updating icon sets

Edit scripts/lib/sets.mjs, then re-run npm run build:data && npm run upload:r2 (local) or npm run deploy (remote). Set priority for /i/{name} best-match is DEFAULT_SET_ORDER in wrangler.toml.

Licensing

Icons are redistributed under their original permissive licenses: Lucide (ISC), Heroicons (MIT), Tabler (MIT), Simple Icons (CC0). Brand marks from Simple Icons are trademarks of their respective owners — use them per each brand's guidelines.

Frequently asked questions

What is io.github.asr-aditya/iconserve?

Icons for agentic development: search & fetch 366,000+ open-source icons as SVG/PNG. No API key.

How do I install io.github.asr-aditya/iconserve?

It runs as a remote server. In Claude Code: claude mcp add --transport http iconserve 'https://icons-for-agents.site/mcp'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.asr-aditya/iconserve need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.asr-aditya/iconserve open source?

Its code is public on GitHub, but the repository does not declare a standard license.

Who maintains io.github.asr-aditya/iconserve?

It is published by asr-aditya. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.