io.github.alisaitteke/noun-mcp

Noun MCP

Languages: English · 简体中文 · Español · Deutsch · 日本語 · Türkçe

Ask for icons in plain words. Describe what you need — "a solid coffee cup, public domain" — and your AI assistant searches The Noun Project, picks a match, and downloads SVG or PNG into your project. Works with Cursor, Claude Desktop, and Claude Code.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by The Noun Project.

What can it do?

• Search — filter by style, line weight, and public-domain license
• Download — SVG or PNG, custom color and size, saved to a path you choose
• Browse collections — curated icon sets, not just one-off searches
• Autocomplete — get better search terms before you burn quota
• Track usage — hourly, daily, and monthly service vs icon windows
• Stay on the free trial — client-side caps so 150 icon calls/month last longer

Under the hood: 7 tools — full list in docs/available-tools.md.

Try saying

Find solid public-domain coffee cup icons, then download one as a red SVG into ./icons.

Suggest search terms for "spo", then search weather collections.

How many Noun Project API calls have I used this month?

Get started

You need Node.js 18+ and Noun Project API keys (create an app — a free account works). Set NOUN_API_TIER to FREE (2,000 service / 150 icon calls per month) or PAID. Quota details: docs/available-tools.md.

Replace your_key / your_secret with your Consumer Key and Secret after install.

Claude Code:

claude mcp add \
  --transport stdio \
  noun-project \
  --env NOUN_CONSUMER_KEY=your_key \
  --env NOUN_CONSUMER_SECRET=your_secret \
  --env NOUN_API_TIER=FREE \
  -- npx -y @alisaitteke/noun-mcp

Or add this to your MCP client's config (Cursor, Claude Desktop, …):

{
  "mcpServers": {
    "noun-project": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/noun-mcp"],
      "env": {
        "NOUN_CONSUMER_KEY": "your_key",
        "NOUN_CONSUMER_SECRET": "your_secret",
        "NOUN_API_TIER": "FREE"
      }
    }
  }
}

Ready-made files: examples/cursor-config.json, examples/claude-desktop-config.json.

How it works

1. You type what you want in plain language.
2. The AI searches first — search_icons is a cheap service call and already returns IDs, license, and thumbnails.
3. Download only when you need a file — each download_icon / get_icon spends an icon call.

Hit a quota error? Ask for check_usage, then wait or refine. Common fixes: docs/troubleshooting.md.

Documentation

• Available tools — all 7 tools, parameters, FREE vs PAID
• Troubleshooting — keys, 429s, public-domain downloads
• Architecture — OAuth, queue, retry, cache
• Development — build from source, tests

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.

Maintainer

Built by Ali Sait Teke — GitHub · LinkedIn.

License

MIT