Noun MCP Server

⚠️ Unofficial Project · This is an independent third-party tool using The Noun Project API. Not affiliated with or endorsed by The Noun Project.

MCP (Model Context Protocol) server for searching, downloading, and using icons from The Noun Project in Cursor AI, Claude Desktop, and other MCP-supported AI tools.

🚀 Quick Start

Cursor AI

Add 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 to 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 in 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 →

What is this? A bridge that lets AI assistants search and download professional icons for your projects. No manual browsing needed - just ask your AI!

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

Requirements

Node.js 18 or higher (Download)
The Noun Project API Keys (free account works!)

Don't have API keys? Get them here →

Quick Start

Step 1: Get Your API Keys

Go to The Noun Project Developers
Sign in or create a free account
Create a new app (or select an existing one)
Copy your Consumer Key and Consumer Secret

Step 2: Installation

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

Step 3: 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)

Perfect 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

Switch anytime: Just update NOUN_API_TIER in your .env file!

Step 4: Configure Cursor AI

Open Cursor settings: Settings → Features → MCP

Add this configuration:

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

Step 5: Configure Claude Desktop

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

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

Usage Examples

Once configured, just talk to your AI naturally:

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

The AI can use these tools to help you:

`search_icons`

Search The Noun Project icon database.

What you can filter:

Style: solid, line, or both
Line weight: 1-60 or 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
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.

Returns:

Icon name and ID
Creator information
Tags and collections
License details
Download URLs

Example:

"Show me details for icon 12345"

`download_icon`

Download an icon with custom options.

Options:

Format: SVG or PNG
Color: Any hex color (e.g., "FF0000" for red)
Size: 20-1200 pixels (PNG only)
Save to file: Optional file path

Note: 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.

Shows:

Monthly limit and usage
Remaining calls
Percentage used
Days until reset
Optimization tips (FREE tier)

FREE Tier Best Practices

Maximize your 5,000 monthly calls:

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
Collection information

Cost Optimization

The server automatically optimizes API usage in FREE tier mode:

Feature	FREE Tier	PAID Tier
Results per page	10 max	100 max
Default thumbnail	42px	84px
SVG URLs	Excluded	Included
Pagination warnings	Yes	No
Usage alerts	50%, 80%, 95%	None

Want full details? See COST_OPTIMIZATION.md

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:

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

"Authentication failed"

Problem: Invalid API credentials.

Solution:

Verify credentials at developers page
Make sure you copied the entire key/secret
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:

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

API Limits

Tier	Monthly Limit	Rate Limit	Download Access
FREE	5,000 calls	100/min	Public domain only
PAID	Unlimited	100/min	All icons

Want more? Check The Noun Project Pricing

Contributing

Contributions are welcome!

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

License

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

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.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Noun MCP Server

🚀 Quick Start

Features

Requirements

Quick Start

Step 1: Get Your API Keys

Step 2: Installation

Step 3: Configure Environment

FREE vs PAID Tier

Step 4: Configure Cursor AI

Step 5: Configure Claude Desktop

Usage Examples

Search for Icons

Download Icons

Browse Collections

Get Suggestions

Check Usage

Available Tools

search_icons

get_icon

download_icon

search_collections

get_collection

icon_autocomplete

check_usage

FREE Tier Best Practices

1. Be Specific

2. Use Autocomplete First

3. Avoid Pagination

4. Download Once, Reuse

5. Filter for Public Domain

6. Cache Results

Cost Optimization

Development

Run in Development Mode

Build for Production

Run Built Version

Project Structure

Troubleshooting

"Missing required environment variables"

"Authentication failed"

"Rate limit exceeded"

SVG URLs Not Working

"Free API access is limited to public domain icons"

Server Not Appearing in Cursor/Claude

API Limits

Contributing

License

Acknowledgments

Author

Support

Links

`search_icons`

`get_icon`

`download_icon`

`search_collections`

`get_collection`

`icon_autocomplete`

`check_usage`