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:

Claude Desktop

Add to config:

Claude Code

Run in terminal:

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

• Easy Setup: Install and run in minutes

• Secure: OAuth 1.0a authentication

• Fast: Built-in rate limiting and caching

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

1. Go to The Noun Project Developers

2. Sign in or create a free account

3. Create a new app (or select an existing one)

4. Copy your Consumer Key and Consumer Secret

Step 2: Installation

Option A: npx (Easiest - No Install Required)

Option B: Global Install

Option C: Local Development

Step 3: Configure Environment

Create a .env file in the project directory:

Edit .env with your credentials:

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)

Option B: Using global install

Option C: Using local build

Step 5: Configure Claude Desktop

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

Using npx (Recommended)

Usage Examples

Once configured, just talk to your AI naturally:

Search for Icons

Download Icons

Browse Collections

Get Suggestions

Check Usage

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:

get_icon

Get detailed information about a specific icon.

Returns:

• Icon name and ID

• Creator information

• Tags and collections

• License details

• Download URLs

Example:

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:

search_collections

Find icon collections by keyword.

Example:

get_collection

View a specific collection with all its icons.

Example:

icon_autocomplete

Get search term suggestions (max 10).

Example:

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

2. Use Autocomplete First

3. Avoid Pagination

4. Download Once, Reuse

5. Filter for Public Domain

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:

Want full details? See COST_OPTIMIZATION.md

Development

Run in Development Mode

Build for Production

Run Built Version

Project Structure

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

Want more? Check The Noun Project Pricing

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

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

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.