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 和开发者社区精心打造的！