Noun MCP

🚀 Noun MCP Server

The Noun MCP Server is an MCP (Model Context Protocol) server that enables users to search for, download, and use icons from The Noun Project in AI tools such as Cursor AI, Claude Desktop, and other MCP - supported AI applications. It provides a convenient way for AI assistants to access professional icons for projects without manual browsing.

🚀 Quick Start

For Different AI Tools

• Cursor AI: Add the following to MCP settings:

  {
    "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"
        }
      }
    }
  }
  

• Claude Desktop: Add the following to the config:

  {
    "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"
        }
      }
    }
  }
  

• Claude Code: Run the following in the terminal:

  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
  

Get your API keys →

✨ Features

• Icon Search: Find icons with filters for style, line weight, and licensing.
• Icon Download: Get SVG or PNG files with custom colors and sizes.
• Collection Browser: Explore curated icon collections.
• Smart Suggestions: Autocomplete helps find the right search terms.
• Usage Tracking: Monitor your API usage and limits.
• FREE Tier Mode: Smart optimizations for 5K monthly API calls.
• PAID Tier Mode: Unlimited access with no restrictions.

📦 Installation

Prerequisites

• Node.js 18 or higher (Download)
• The Noun Project API Keys (a free account works!) Don't have API keys? Get them here →

Installation Options

• Option A: npx (Easiest - No Install Required)

  # Run directly without installation
  npx @alisaitteke/noun-mcp
  

• Option B: Global Install

  npm install -g @alisaitteke/noun-mcp
  

• Option C: Local Development

  git clone https://github.com/alisaitteke/noun-mcp.git
  cd noun-mcp
  npm install
  npm run build
  npm link
  

Configure Environment

Create a .env file in the project directory:

cp .env.example .env

Edit .env with your credentials:

# Your API credentials from The Noun Project
NOUN_CONSUMER_KEY=your_consumer_key_here
NOUN_CONSUMER_SECRET=your_consumer_secret_here

# Choose your tier: FREE (5K calls/month) or PAID (unlimited)
NOUN_API_TIER=FREE

FREE vs PAID Tier

FREE Tier (5,000 API calls/month)

• Ideal for personal projects and testing.
• Automatic cost optimizations.
• Smaller page sizes (max 10 results per search).
• Optimized thumbnails (42px by default).
• SVG URLs excluded by default (save bandwidth).
• Smart usage alerts at 50%, 80%, 95%.

PAID Tier (Unlimited)

• No monthly limits.
• Larger page sizes (up to 100 results).
• High - quality thumbnails (84px by default).
• SVG URLs included automatically.
• No restrictions.

You can switch between tiers anytime by updating NOUN_API_TIER in your .env file.

Configure Cursor AI

Open Cursor settings: Settings → Features → MCP

• Option A: Using npx (Recommended)

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

• Option B: Using global install

  {
    "mcpServers": {
      "noun-project": {
        "command": "noun-mcp",
        "env": {
          "NOUN_CONSUMER_KEY": "your_key_here",
          "NOUN_CONSUMER_SECRET": "your_secret_here",
          "NOUN_API_TIER": "FREE"
        }
      }
    }
  }
  

• Option C: Using local build

  {
    "mcpServers": {
      "noun-project": {
        "command": "node",
        "args": ["/path/to/noun-mcp/dist/index.js"],
        "env": {
          "NOUN_CONSUMER_KEY": "your_key_here",
          "NOUN_CONSUMER_SECRET": "your_secret_here",
          "NOUN_API_TIER": "FREE"
        }
      }
    }
  }
  

Configure Claude Desktop

Edit: ~/Library/Application Support/Claude/claude_desktop_config.json

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

💻 Usage Examples

Search for Icons

"Find me some coffee cup icons"
"Search for solid style house icons"
"Show me line icons with weight 18 - 20 for 'bicycle'"

Download Icons

"Download icon 12345 in red color"
"Get icon 67890 as PNG, 200x200 pixels, save to ./icons/house.png"
"Download this icon as SVG with hex color FF5733"

Browse Collections

"Search for weather icon collections"
"Show me collection 123 details"

Get Suggestions

"Give me autocomplete suggestions for 'spo'"

Check Usage

"How many API calls have I used this month?"
"Check my API usage limits"

📚 Available Tools

search_icons

Search The Noun Project icon database. You can filter by style (solid, line, or both), line weight (1 - 60 or a range like "18 - 20"), public domain (show only free - to - use icons), thumbnail size (42, 84, or 200 pixels), include SVG (get SVG URLs in results), and limit (max results per page). Example:

"Search for 'coffee' icons in solid style, public domain only"

get_icon

Get detailed information about a specific icon, including icon name and ID, creator information, tags and collections, license details, and download URLs. Example:

"Show me details for icon 12345"

download_icon

Download an icon with custom options such as format (SVG or PNG), color (any hex color), size (20 - 1200 pixels for PNG only), and an optional save - to - file path. Note that the FREE tier can only download public domain icons. Example:

"Download icon 12345 as PNG, 200x200, red color, save to ./icons/coffee.png"

search_collections

Find icon collections by keyword. Example:

"Search for 'travel' collections"

get_collection

View a specific collection with all its icons. Example:

"Show me collection 456"

icon_autocomplete

Get search term suggestions (max 10). Example:

"What terms start with 'comp'?"

check_usage

Check your API usage and limits, showing monthly limit and usage, remaining calls, percentage used, days until reset, and optimization tips (FREE tier).

📈 FREE Tier Best Practices

1. Be Specific

Bad:  "icon"       → Too broad, many pages needed
Good: "coffee cup" → Specific, better results

2. Use Autocomplete First

Step 1: "Suggestions for 'cof'"  → ["coffee", "coffee cup"]
Step 2: "Search for 'coffee cup'" → Exact results

3. Avoid Pagination

Bad:  Browsing 5 pages = 5 API calls
Good: Refine search to get results on first page

4. Download Once, Reuse

Download icon → Save to project → Use everywhere
(Don't re - download the same icon)

5. Filter for Public Domain

FREE tier can only download public domain icons
Filter searches with limit_to_public_domain=1

6. Cache Results

The server automatically caches usage data for 5 minutes. You should also save downloaded icons, icon IDs you've explored, and collection information.

📊 Cost Optimization

The server automatically optimizes API usage in FREE tier mode:

See COST_OPTIMIZATION.md for full details.

🔧 Development

Run in Development Mode

npm install
npm run dev

Build for Production

npm run build

Run Built Version

npm start

Project Structure

noun-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── api/
│   │   ├── auth.ts          # OAuth 1.0a authentication
│   │   └── client.ts        # API client with rate limiting
│   ├── tools/
│   │   ├── search.ts        # Icon search functionality
│   │   ├── download.ts      # Icon download & details
│   │   ├── collections.ts   # Collections & autocomplete
│   │   └── usage.ts         # Usage monitoring
│   ├── types/
│   │   └── schemas.ts       # Zod schemas & TypeScript types
│   └── utils/
│       └── costOptimizer.ts # Cost optimization logic
├── package.json
├── tsconfig.json
└── README.md

🐞 Troubleshooting

"Missing required environment variables"

Problem: API keys not found. Solution:

1. Check .env file exists.
2. Verify NOUN_CONSUMER_KEY and NOUN_CONSUMER_SECRET are set.
3. Check for typos in variable names.

"Authentication failed"

Problem: Invalid API credentials. Solution:

1. Verify credentials at developers page.
2. Make sure you copied the entire key/secret.
3. Check for extra spaces or quotes.

"Rate limit exceeded"

Problem: Too many requests too fast. Solution:

• Wait a moment (limit is 100 requests/minute).
• The server automatically handles rate limiting.
• If persistent, check your usage with check_usage tool.

SVG URLs Not Working

Problem: SVG URLs expire after 1 hour. Solution:

• Download fresh URLs when needed.
• Use download_icon to get base64 - encoded icons.
• Save icons locally instead of relying on URLs.

"Free API access is limited to public domain icons"

Problem: Trying to download non - public - domain icon with FREE account. Solution:

• Filter searches: limit_to_public_domain=1.
• Or upgrade to PAID tier at pricing page.

Server Not Appearing in Cursor/Claude

Problem: MCP server not detected. Solution:

1. Restart Cursor AI or Claude Desktop.
2. Check JSON config syntax (no trailing commas!).
3. Verify file paths are absolute.
4. Check server logs for errors.

📄 API Limits

Check The Noun Project Pricing for more.

🤝 Contributing

Contributions are welcome!

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing - feature.
3. Commit changes: git commit -m 'Add amazing feature'.
4. Push to branch: git push origin feature/amazing - feature.
5. Open a Pull Request.

📄 License

This project is under the MIT License. See LICENSE file for details.

💖 Acknowledgments

• The Noun Project - For the amazing icon collection.
• Model Context Protocol - For the MCP specification.
• Anthropic - For Claude and MCP development.

📦 Author

Ali Sait Teke

• GitHub: @alisaitteke
• NPM: @alisaitteke

📧 Support

• Issues: GitHub Issues
• Documentation: The Noun Project API Docs
• Pricing: The Noun Project Plans

🔗 Links

• The Noun Project
• The Noun Project API
• MCP Documentation
• Cursor AI
• Claude

Note: This is a community - built MCP server and is not an official product of The Noun Project.

Made with ❤️ for the AI and developer community.