🤗 Hugging Face MCP Server 🤗

🤗 Hugging Face MCP Server 🤗

一个 Model Context Protocol（MCP）服务，可只读访问 Hugging Face Hub API。此服务允许 Claude 等大模型与 Hugging Face 的模型、数据集、Spaces、论文和集合进行交互。

组件

资源

此服务公开了常用的 Hugging Face 资源：

• 用于访问资源的自定义 hf:// URI 方案
• URI 为 hf://model/{model_id} 的模型
• URI 为 hf://dataset/{dataset_id} 的数据集
• URI 为 hf://space/{space_id} 的 Spaces
• 所有资源都有描述性名称和 JSON 内容类型

提示词

此服务提供两个提示词模板：

• compare-models：生成多个 Hugging Face 模型的比较结果

  • 必需的 model_ids 参数（以逗号分隔的模型 ID）
  • 获取模型详情并整理为比较内容

• summarize-paper：总结 Hugging Face 上的研究论文

  • 用于识别论文的必需 arxiv_id 参数
  • 可选的 detail_level 参数（brief/detailed），用于控制总结的详细程度
  • 将论文元数据与实现细节结合起来

工具

此服务实现了多个工具类别：

• 模型工具

  • search-models：按查询、作者、标签和数量限制筛选并搜索模型
  • get-model-info：获取特定模型的详细信息

• 数据集工具

  • search-datasets：按筛选条件搜索数据集
  • get-dataset-info：获取特定数据集的详细信息

• Space 工具

  • search-spaces：按筛选条件搜索 Spaces，包括 SDK 类型
  • get-space-info：获取特定 Space 的详细信息

• 论文工具

  • get-paper-info：获取论文及其实现的信息
  • get-daily-papers：获取精选每日论文列表

• 集合工具

  • search-collections：按各种筛选条件搜索集合
  • get-collection-info：获取特定集合的详细信息

配置

此服务无需配置，但支持可选的 Hugging Face 身份验证：

• 设置 HF_TOKEN 环境变量，并填入你的 Hugging Face API 令牌，以获得：
  • 更高的 API 速率限制
  • 访问私有仓库的权限（需获得授权）
  • 提高大量请求时的可靠性

快速入门

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 huggingface-mcp-server：

npx -y @smithery/cli install @shreyaskarnik/huggingface-mcp-server --client claude

Claude Desktop

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "huggingface": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/huggingface-mcp-server",
      "run",
      "huggingface_mcp_server.py"
    ],
    "env": {
      "HF_TOKEN": "your_token_here"  // Optional
    }
  }
}

开发

构建和发布

准备发布软件包：

1. 同步依赖项并更新锁文件：

uv sync

1. 构建软件包分发文件：

uv build

这将在 dist/ 目录中创建源码分发包和 wheel 分发包。

1. 发布到 PyPI：

uv publish

注意：你需要通过环境变量或命令标志设置 PyPI 凭据：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务通过标准输入输出运行，调试可能颇具挑战。为了获得最佳调试 体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/huggingface-mcp-server run huggingface_mcp_server.py

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 开始调试。

Claude 示例提示词

在 Claude 中使用此服务时，请尝试以下示例提示词：

• "在 Hugging Face 上搜索参数量少于 1 亿的 BERT 模型"
• "查找 Hugging Face 上最受欢迎的文本分类数据集"
• "Hugging Face 今日精选的 AI 研究论文有哪些？"
• "使用 Hugging Face MCP 服务总结 arXiv ID 为 2307.09288 的论文"
• "比较 Hugging Face 上的 Llama-3-8B 和 Mistral-7B 模型"
• "向我展示最受欢迎的图像生成 Gradio 空间"
• "查找 TheBloke 创建的、包含 Mixtral 模型的集合"

故障排除

如果遇到服务问题：

1. 检查 Claude Desktop 中的服务日志：

   • macOS：~/Library/Logs/Claude/mcp-server-huggingface.log
   • Windows：%APPDATA%\Claude\logs\mcp-server-huggingface.log

2. 如果出现 API 速率限制错误，请考虑添加 Hugging Face API 令牌

3. 确保你的计算机可以连接互联网，以访问 Hugging Face API

4. 如果某个工具运行失败，请尝试通过 Hugging Face 网站访问相同的数据，以确认其是否存在