Noun Project

Created By

firecrawla month ago

Content

Noun Project MCP Server

A Model Context Protocol (MCP) server for The Noun Project API, enabling Claude Code to search and retrieve icons programmatically.

Features

Icon Search: Search for icons with advanced filters (style, line weight, public domain)
Icon Details: Get detailed information about specific icons
Collections: Retrieve icon collections
Autocomplete: Get search term suggestions
Usage Tracking: Monitor API quota and usage
Download URLs: Get customized download links with color and size options

Prerequisites

Node.js: Version 18 or higher
Noun Project API Credentials: Get your API key and secret from The Noun Project

Installation

Quick Install (Recommended)

Install directly from npm and add to Claude Code in one command:

claude mcp add --transport stdio noun-project \
  --env NOUN_PROJECT_API_KEY=your_api_key_here \
  --env NOUN_PROJECT_API_SECRET=your_api_secret_here \
  -- npx -y noun-project-mcp

Replace your_api_key_here and your_api_secret_here with your actual credentials from The Noun Project.

Local Development

Clone and navigate to the repository:

git clone https://github.com/sgup/noun-project-mcp.git
cd noun-project-mcp

Install dependencies:

npm install

Build the TypeScript code:

npm run build

Add to Claude Code using local path:

claude mcp add --transport stdio noun-project \
  --env NOUN_PROJECT_API_KEY=your_api_key_here \
  --env NOUN_PROJECT_API_SECRET=your_api_secret_here \
  -- node /absolute/path/to/noun-project-mcp/dist/index.js

Available Tools

1. search_icons

Search for icons with various filters.

Parameters:

query (required): Search term (e.g., "dog", "house")
styles (optional): Filter by style - "solid", "line", or "solid,line"
line_weight (optional): For line icons, specify weight (1-60) or range (e.g., "18-20")
limit_to_public_domain (optional): Set to 1 for public domain only
thumbnail_size (optional): 42, 84, or 200 pixels
include_svg (optional): Set to 1 to include SVG URLs
limit (optional): Maximum number of results

Example:

{
  "query": "dog",
  "styles": "line",
  "limit": 10
}

2. get_icon

Get detailed information about a specific icon.

Parameters:

icon_id (required): The icon's unique ID
thumbnail_size (optional): 42, 84, or 200 pixels

Example:

{
  "icon_id": 12345,
  "thumbnail_size": 200
}

3. get_collection

Retrieve a collection and its icons.

Parameters:

collection_id (required): The collection's unique ID
thumbnail_size (optional): 42, 84, or 200 pixels
include_svg (optional): Set to 1 to include SVG URLs
limit (optional): Maximum number of icons to return

Example:

{
  "collection_id": 123
}

4. icon_autocomplete

Get autocomplete suggestions for search terms.

Parameters:

query (required): Partial search term
limit (optional): Maximum number of suggestions

Example:

{
  "query": "hom",
  "limit": 5
}

5. check_usage

Check current API usage and limits.

Parameters: None

6. get_download_url

Get a download URL for an icon with customization.

Parameters:

icon_id (required): The icon's unique ID
color (optional): Hexadecimal color (e.g., "FF0000")
filetype (optional): "svg" or "png"
size (optional): For PNG, size in pixels (20-1200)

Example:

{
  "icon_id": 12345,
  "color": "FF0000",
  "filetype": "png",
  "size": 512
}

Development

Run in development mode with auto-rebuild:

npm run dev

Build for production:

npm run build

Start the server:

npm start

API Reference

This MCP server uses The Noun Project API v2. For more details about the API:

Authentication

The Noun Project API uses OAuth 1.0 authentication. This server handles all OAuth signing automatically using your API credentials.

Usage Limits

The Noun Project API has monthly usage limits. Use the check_usage tool to monitor your quota.

Troubleshooting

"NOUN_PROJECT_API_KEY and NOUN_PROJECT_API_SECRET must be set"

Make sure you included the --env flags when running claude mcp add. You can verify your configuration with:

claude mcp list

To update your credentials, remove and re-add the server:

claude mcp remove noun-project
claude mcp add --transport stdio noun-project \
  --env NOUN_PROJECT_API_KEY=your_new_key \
  --env NOUN_PROJECT_API_SECRET=your_new_secret \
  -- npx -y noun-project-mcp