Noun Project

Noun Project MCP 服务

一个用于 The Noun Project API 的模型上下文协议（MCP）服务，可让 Claude Code 以编程方式搜索和检索图标。

功能

• 图标搜索：使用高级筛选条件搜索图标（样式、线条粗细、公共领域）
• 图标详情：获取特定图标的详细信息
• 合集：检索图标合集
• 自动补全：获取搜索词建议
• 使用情况跟踪：监控 API 配额和使用情况
• 下载 URL：获取可自定义的下载链接，并设置颜色和尺寸

前提条件

1. Node.js：版本 18 或更高
2. Noun Project API 凭据：从 The Noun Project 获取 API 密钥和密钥

安装

快速安装（推荐）

直接从 npm 安装，并通过一条命令添加到 Claude Code：

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

将 your_api_key_here 和 your_api_secret_here 替换为你从 The Noun Project 获取的实际凭据。

本地开发

1. 克隆并进入仓库：

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

2. 安装依赖：

npm install

3. 构建 TypeScript 代码：

npm run build

4. 使用本地路径添加到 Claude Code：

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

可用工具

1. search_icons

使用各种筛选条件搜索图标。

参数：

• query（必填）：搜索词（例如，“dog”“house”）
• styles（可选）：按样式筛选——“solid”“line”或“solid,line”
• line_weight（可选）：对于线条图标，指定粗细（1-60）或范围（例如，“18-20”）
• limit_to_public_domain（可选）：设为 1，仅搜索公共领域图标
• thumbnail_size（可选）：42、84 或 200 像素
• include_svg（可选）：设为 1，以包含 SVG URL
• limit（可选）：结果数量上限

示例：

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

2. get_icon

获取特定图标的详细信息。

参数：

• icon_id（必填）：图标的唯一 ID
• thumbnail_size（可选）：42、84 或 200 像素

示例：

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

3. get_collection

检索一个合集及其中的图标。

参数：

• collection_id（必填）：合集的唯一 ID
• thumbnail_size（可选）：42、84 或 200 像素
• include_svg（可选）：设为 1，以包含 SVG URL
• limit（可选）：要返回的图标数量上限

示例：

{
  "collection_id": 123
}

4. icon_autocomplete

获取搜索词的自动补全建议。

参数：

• query（必填）：部分搜索词
• limit（可选）：建议数量上限

示例：

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

5. check_usage

查看当前 API 使用情况和限制。

参数： 无

6. get_download_url

获取可自定义图标的下载 URL。

参数：

• icon_id（必填）：图标的唯一 ID
• color（可选）：十六进制颜色（例如，“FF0000”）
• filetype（可选）：“svg”或“png”
• size（可选）：对于 PNG，指定像素尺寸（20-1200）

示例：

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

开发

在开发模式下运行并自动重新构建：

npm run dev

构建生产版本：

npm run build

启动服务：

npm start

API 参考

此 MCP 服务使用 The Noun Project API v2。有关 API 的更多详情，请参阅：

• API 文档
• 迁移指南

身份验证

The Noun Project API 使用 OAuth 1.0 身份验证。此服务会使用你的 API 凭据自动处理所有 OAuth 签名。

使用限制

The Noun Project API 有每月使用量限制。使用 check_usage 工具监控你的配额。

故障排除

“NOUN_PROJECT_API_KEY and NOUN_PROJECT_API_SECRET must be set”

运行 claude mcp add 时，请确保包含 --env 标志。你可以使用以下命令验证配置：

claude mcp list

要更新凭据，请移除并重新添加服务：

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

“Invalid signature” 错误

请确认 API 密钥和密钥正确，且未在 The Noun Project 控制面板中重新生成。

连接问题

请确保网络连接正常，并且可以访问 The Noun Project API。

许可证

MIT

支持

如果此 MCP 服务出现问题，请在代码仓库中提交 issue。

如果 The Noun Project API 出现问题，请访问其支持页面。