Noun MCP

🚀 Noun MCP Server

Noun MCP Server 是一個 MCP（模型上下文協議）服務器，可用於在 Cursor AI、Claude Desktop 等支持 MCP 的 AI 工具中搜索、下載和使用來自 The Noun Project 的圖標。

🚀 快速開始

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

FREE 與 PAID 套餐對比

• FREE 套餐（每月 5000 次 API 調用）：
  • 適合個人項目和測試。
  • 自動進行成本優化。
  • 每頁結果較少（每次搜索最多 10 條結果）。
  • 默認優化縮略圖（默認 42px）。
  • 默認不包含 SVG 鏈接（節省帶寬）。
  • 在使用量達到 50%、80%、95% 時會有智能使用提醒。
• PAID 套餐（無限制）：
  • 無每月調用限制。
  • 每頁結果更多（最多 100 條結果）。
  • 高質量縮略圖（默認 84px）。
  • 自動包含 SVG 鏈接。
  • 無任何使用限制。

你可以隨時通過更新 .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"
      }
    }
  }
}

✨ 主要特性

• 圖標搜索：可通過風格、線條粗細和許可類型等過濾器查找圖標。
• 圖標下載：獲取具有自定義顏色和尺寸的 SVG 或 PNG 文件。
• 圖標集瀏覽：探索精心策劃的圖標集。
• 智能建議：自動補全功能幫助找到合適的搜索詞。
• 使用情況跟蹤：監控 API 使用情況和限制。
• 免費套餐模式：針對每月 5000 次 API 調用進行智能優化。
• 付費套餐模式：無限制訪問，無任何使用限制。

📦 安裝指南

安裝要求

• Node.js 18 或更高版本（下載地址）。
• The Noun Project API 密鑰（免費賬號即可）。

如果你還沒有 API 密鑰，可以點擊這裡獲取。

💻 使用示例

配置完成後，你可以自然地與 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 鏈接。
    • 每頁最大結果數。
  • 示例：

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

• get_icon：獲取特定圖標的詳細信息。
  • 返回信息：
    • 圖標名稱和 ID。
    • 創建者信息。
    • 標籤和圖標集。
    • 許可詳情。
    • 下載鏈接。
  • 示例：

"Show me details for icon 12345"

• download_icon：使用自定義選項下載圖標。
  • 選項：
    • 格式：SVG 或 PNG。
    • 顏色：任何十六進制顏色（如 "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 使用情況和限制。
  • 顯示信息：
    • 每月限制和使用量。
    • 剩餘調用次數。
    • 已使用百分比。
    • 重置剩餘天數。
    • 免費套餐的優化提示。

FREE 套餐最佳實踐

為了最大化每月 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 使用：

如果你想了解更多詳細信息，請查看 COST_OPTIMIZATION.md。

開發

• 開發模式運行：

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"
  • 問題：請求速度過快，超過了速率限制。
  • 解決方案：
    • 等待片刻（限制為每分鐘 100 次請求）。
    • 服務器會自動處理速率限制。
    • 如果問題仍然存在，使用 check_usage 工具檢查使用情況。
• SVG 鏈接無法使用
  • 問題：SVG 鏈接在 1 小時後會過期。
  • 解決方案：
    • 需要時下載新的鏈接。
    • 使用 download_icon 獲取 Base64 編碼的圖標。
    • 將圖標保存到本地，而不是依賴鏈接。
• "Free API access is limited to public domain icons"
  • 問題：使用免費賬號嘗試下載非公共領域的圖標。
  • 解決方案：
    • 在搜索時添加 limit_to_public_domain=1 進行過濾。
    • 或在 定價頁面 升級到付費套餐。
• 服務器未在 Cursor/Claude 中顯示
  • 問題：MCP 服務器未被檢測到。
  • 解決方案：
    1. 重啟 Cursor AI 或 Claude Desktop。
    2. 檢查 JSON 配置語法（不要有尾隨逗號！）。
    3. 驗證文件路徑是否為絕對路徑。
    4. 檢查服務器日誌是否有錯誤信息。

🔧 技術細節

API 限制

如果你想了解更多信息，請查看 The Noun Project Pricing。

📄 許可證

本項目採用 MIT 許可證，詳情請查看 LICENSE 文件。

👐 貢獻

歡迎貢獻代碼！貢獻步驟如下：

1. 分叉倉庫。
2. 創建一個功能分支：git checkout -b feature/amazing-feature。
3. 提交更改：git commit -m 'Add amazing feature'。
4. 推送到分支：git push origin feature/amazing-feature。
5. 打開一個拉取請求。

👏 致謝

• 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 文檔
• Cursor AI
• Claude

⚠️ 重要提示

這是一個社區構建的 MCP 服務器，並非 The Noun Project 的官方產品。

本項目是為 AI 和開發者社區精心打造的！