🤗 Hugging Face MCP Server 🤗

这是一个提供只读访问Hugging Face Hub API的模型上下文协议（MCP）服务器。此服务器允许像Claude这样的大语言模型与Hugging Face的模型、数据集、空间、论文和集合进行交互。

组件

资源

该服务器公开了流行的Hugging Face资源：

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

提示

该服务器提供了两个提示模板：

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

  • 需要model_ids参数（逗号分隔的模型ID）
  • 获取模型详情并格式化以进行比较

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

  • 需要arxiv_id参数用于识别论文
  • 可选的detail_level参数（简略/详细）控制摘要深度
  • 结合论文元数据与实现细节

工具

该服务器实现了几个工具类别：

• 模型工具

  • search-models：通过查询、作者、标签和限制过滤器搜索模型
  • get-model-info：获取特定模型的详细信息

• 数据集工具

  • search-datasets：通过过滤器搜索数据集
  • get-dataset-info：获取特定数据集的详细信息

• 空间工具

  • search-spaces：通过包括SDK类型的过滤器搜索空间
  • get-space-info：获取特定空间的详细信息

• 论文工具

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

• 集合工具

  • search-collections：通过各种过滤器搜索集合
  • get-collection-info：获取特定集合的详细信息

配置

该服务器不需要配置，但支持可选的Hugging Face身份验证：

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

快速开始

安装

通过Smithery安装

要通过Smithery自动安装huggingface-mcp-server供Claude Desktop使用：

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`

<details> <summary>开发/未发布服务器配置</summary>

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

</details>

开发

构建和发布

为了准备分发的包：

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

uv sync

1. 构建包分布：

uv build

这将在dist/目录中创建源和轮子分布。

1. 发布到PyPI：

uv publish

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

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

调试

由于MCP服务器通过标准I/O运行，调试可能会很困难。为了最佳的调试体验，我们强烈建议使用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网站访问相同的数据以验证其存在性 </中文翻译>