Noun MCP

🚀 Noun MCP Server

Cursor AIやClaude DesktopなどのMCP対応AIツールで、The Noun Projectからアイコンを検索、ダウンロード、使用するためのMCP（Model Context Protocol）サーバーです。

🚀 クイックスタート

各AIツールへの設定方法

APIキーを取得する →

⚠️ 重要提示

このプロジェクトは非公式のものです。The Noun Project APIを使用した独立したサードパーティツールであり、The Noun Projectとは関係がありません。

✨ 主な機能

• アイコン検索：スタイル、線の太さ、ライセンスなどのフィルターを使ってアイコンを検索できます。
• アイコンダウンロード：カスタムカラーやサイズでSVGまたはPNGファイルを取得できます。
• コレクションブラウザ：選りすぐりのアイコンコレクションを探索できます。
• スマートな提案：オートコンプリート機能で適切な検索用語を見つけやすくなります。
• 使用状況の追跡：APIの使用状況と制限を監視できます。
• 無料プランモード：月5000回のAPI呼び出しに対するスマートな最適化が行われます。
• 有料プランモード：制限なしの無制限アクセスが可能です。

📦 インストール

ステップ1: APIキーの取得

1. The Noun Project Developersにアクセスします。
2. サインインするか、無料アカウントを作成します。
3. 新しいアプリを作成するか、既存のアプリを選択します。
4. Consumer KeyとConsumer Secretをコピーします。

ステップ2: インストール方法の選択

オプションA: npx（最も簡単 - インストール不要）

# インストールせずに直接実行
npx @alisaitteke/noun-mcp

オプションB: グローバルインストール

npm install -g @alisaitteke/noun-mcp

オプションC: ローカル開発

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

ステップ3: 環境変数の設定

プロジェクトディレクトリに.envファイルを作成します。

cp .env.example .env

.envファイルを編集し、認証情報を設定します。

# The Noun Projectから取得したAPI認証情報
NOUN_CONSUMER_KEY=your_consumer_key_here
NOUN_CONSUMER_SECRET=your_consumer_secret_here

# プランを選択: FREE（月5000回の呼び出し）またはPAID（無制限）
NOUN_API_TIER=FREE

無料プランと有料プランの比較

💡 使用建议

いつでもプランを切り替えることができます。.envファイルのNOUN_API_TIERを更新するだけです。

ステップ4: Cursor AIの設定

Cursorの設定を開きます：Settings → Features → MCP 以下の設定を追加します。

オプションA: npxを使用する（推奨）

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

オプションB: グローバルインストールを使用する

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

オプションC: ローカルビルドを使用する

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

ステップ5: Claude Desktopの設定

~/Library/Application Support/Claude/claude_desktop_config.jsonを編集します。

npxを使用する（推奨）

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

💻 使用例

設定が完了したら、自然にAIと会話するだけです。

アイコンの検索

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

アイコンのダウンロード

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

コレクションの閲覧

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

提案の取得

"Give me autocomplete suggestions for 'spo'"

使用状況の確認

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

🔧 利用可能なツール

AIは以下のツールを使用してあなたを支援します。

search_icons

The Noun Projectのアイコンデータベースを検索します。

フィルター可能な項目:

• スタイル: solid、line、または両方
• 線の太さ: 1-60 または "18-20" のような範囲
• 公共ドメイン: 無料で使用できるアイコンのみを表示
• サムネイルサイズ: 42、84、または 200 ピクセル
• SVGを含める: 結果にSVGのURLを取得
• 制限: ページごとの最大結果数

例:

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

get_icon

特定のアイコンに関する詳細情報を取得します。

返される情報:

• アイコンの名前とID
• 作成者情報
• タグとコレクション
• ライセンスの詳細
• ダウンロードURL

例:

"Show me details for icon 12345"

download_icon

カスタムオプションでアイコンをダウンロードします。

オプション:

• 形式: SVGまたはPNG
• 色: 任意の16進数カラー（例: "FF0000" は赤色）
• サイズ: 20-1200ピクセル（PNGのみ）
• ファイルに保存: オプションのファイルパス

注意: 無料プランでは公共ドメインのアイコンのみダウンロードできます。

例:

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

search_collections

キーワードでアイコンコレクションを検索します。

例:

"Search for 'travel' collections"

get_collection

特定のコレクションとそのすべてのアイコンを表示します。

例:

"Show me collection 456"

icon_autocomplete

検索用語の提案を取得します（最大10件）。

例:

"What terms start with 'comp'?"

check_usage

APIの使用状況と制限を確認します。

表示される情報:

• 月額制限と使用状況
• 残りの呼び出し回数
• 使用割合
• リセットまでの日数
• 最適化のヒント（無料プラン）

📚 無料プランのベストプラクティス

月5000回の呼び出しを最大限に活用するための方法です。

1. 具体的な検索を行う

悪い例:  "icon"       → 範囲が広すぎて、多くのページが必要
良い例:  "coffee cup" → 具体的で、良い結果が得られる

2. まずオートコンプリートを使用する

ステップ1: "Suggestions for 'cof'"  → ["coffee", "coffee cup"]
ステップ2: "Search for 'coffee cup'" → 正確な結果が得られる

3. ページネーションを避ける

悪い例:  5ページを閲覧する = 5回のAPI呼び出し
良い例:  検索を絞り込んで、最初のページで結果を取得する

4. 一度ダウンロードしたアイコンを再利用する

アイコンをダウンロード → プロジェクトに保存 → どこでも使用する
（同じアイコンを再ダウンロードしない）

5. 公共ドメインのアイコンをフィルターする

無料プランでは公共ドメインのアイコンのみダウンロードできます。
limit_to_public_domain=1 で検索をフィルターします。

6. 結果をキャッシュする

サーバーは使用状況データを自動的に5分間キャッシュします。 以下のものも保存することをおすすめします。

• ダウンロードしたアイコン
• 探索したアイコンのID
• コレクション情報

📚 コスト最適化

サーバーは無料プランモードでAPIの使用を自動的に最適化します。

詳細を確認する →

🔧 開発

開発モードで実行

npm install
npm run dev

本番用にビルド

npm run build

ビルドしたバージョンを実行

npm start

プロジェクト構造

noun-mcp/
├── src/
│   ├── index.ts              # MCPサーバーのエントリーポイント
│   ├── api/
│   │   ├── auth.ts          # OAuth 1.0a認証
│   │   └── client.ts        # レート制限付きのAPIクライアント
│   ├── tools/
│   │   ├── search.ts        # アイコン検索機能
│   │   ├── download.ts      # アイコンのダウンロードと詳細
│   │   ├── collections.ts   # コレクションとオートコンプリート
│   │   └── usage.ts         # 使用状況の監視
│   ├── types/
│   │   └── schemas.ts       # ZodスキーマとTypeScriptの型
│   └── utils/
│       └── costOptimizer.ts # コスト最適化のロジック
├── package.json
├── tsconfig.json
└── README.md

📚 トラブルシューティング

"Missing required environment variables"

問題: APIキーが見つかりません。

解決策:

1. .envファイルが存在することを確認します。
2. NOUN_CONSUMER_KEYとNOUN_CONSUMER_SECRETが設定されていることを確認します。
3. 変数名のスペルミスを確認します。

"Authentication failed"

問題: 無効なAPI認証情報です。

解決策:

1. 開発者ページで認証情報を確認します。
2. キー/シークレット全体を正しくコピーしたことを確認します。
3. 余分なスペースや引用符を確認します。

"Rate limit exceeded"

問題: 短時間に多くのリクエストを送信しました。

解決策:

• しばらく待ってから再度試してください（制限は1分間に100リクエスト）。
• サーバーは自動的にレート制限を処理します。
• 問題が解決しない場合は、check_usageツールで使用状況を確認します。

SVG URLs Not Working

問題: SVGのURLは1時間後に期限切れになります。

解決策:

• 必要なときに新しいURLをダウンロードします。
• download_iconを使用してBase64エンコードされたアイコンを取得します。
• URLに依存するのではなく、アイコンをローカルに保存します。

"Free API access is limited to public domain icons"

問題: 無料アカウントで公共ドメイン以外のアイコンをダウンロードしようとしています。

解決策:

• 検索をフィルターします: limit_to_public_domain=1
• または、価格ページで有料プランにアップグレードします。

Server Not Appearing in Cursor/Claude

問題: MCPサーバーが検出されません。

解決策:

1. Cursor AIまたはClaude Desktopを再起動します。
2. JSON設定の構文を確認します（末尾のコンマは使用しないでください！）。
3. ファイルパスが絶対パスであることを確認します。
4. サーバーのログを確認して、エラーを確認します。

📚 API制限

The Noun Projectの価格ページを確認する →

🤝 コントリビューション

コントリビューションは大歓迎です！

1. リポジトリをフォークします。
2. 機能ブランチを作成します: git checkout -b feature/amazing-feature
3. 変更をコミットします: git commit -m 'Add amazing feature'
4. ブランチにプッシュします: git push origin feature/amazing-feature
5. プルリクエストを開きます。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

💖 謝辞

• The Noun Project - 素晴らしいアイコンコレクションを提供してくれました。
• Model Context Protocol - MCP仕様を提供してくれました。
• Anthropic - ClaudeとMCPの開発に貢献してくれました。

📦 作者

Ali Sait Teke

• GitHub: @alisaitteke
• NPM: @alisaitteke

📧 サポート

• 問題報告: GitHub Issues
• ドキュメント: The Noun Project API Docs
• 価格情報: The Noun Project Plans

🔗 リンク

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

注意: このMCPサーバーはコミュニティによって構築されたものであり、The Noun Projectの公式製品ではありません。

AIと開発者コミュニティのために愛を込めて作られました。