MCP 服务器

Hugging Face MCP Server

一个模型上下文协议服务器，为 Claude 和其他大型语言模型提供对 Hugging Face Hub API 的只读访问权限，从而能够通过自然语言与模型、数据集、Spaces、论文和集合进行交互。

README

🤗 Hugging Face MCP 服务器 🤗

一个模型上下文协议 (MCP) 服务器，提供对 Hugging Face Hub API 的只读访问。此服务器允许像 Claude 这样的 LLM 与 Hugging Face 的模型、数据集、Spaces、论文和集合进行交互。

组件

资源

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

用于访问资源的自定义 hf:// URI 方案
具有 hf://model/{model_id} URI 的模型
具有 hf://dataset/{dataset_id} URI 的数据集
具有 hf://space/{space_id} URI 的 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: 使用包括 SDK 类型在内的过滤器搜索 Spaces
- get-space-info: 获取有关特定 Space 的详细信息
论文工具
- get-paper-info: 获取有关论文及其实现的信息
- get-daily-papers: 获取精选的每日论文列表
集合工具
- search-collections: 使用各种过滤器搜索集合
- get-collection-info: 获取有关特定集合的详细信息

配置

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

使用您的 Hugging Face API 令牌设置 HF_TOKEN 环境变量，以获得：
- 更高的 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

<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>

开发

构建和发布

要准备用于分发的软件包：

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

uv sync

构建软件包分发：

uv build

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

发布到 PyPI：

uv publish

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

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

调试

由于 MCP 服务器通过 stdio 运行，因此调试可能具有挑战性。为了获得最佳的调试体验，我们强烈建议使用 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 Spaces"
"查找由 TheBloke 创建的包含 Mixtral 模型的集合"

故障排除

如果您遇到服务器问题：

检查 Claude Desktop 中的服务器日志：
- macOS: ~/Library/Logs/Claude/mcp-server-huggingface.log
- Windows: %APPDATA%\Claude\logs\mcp-server-huggingface.log
对于 API 速率限制错误，请考虑添加 Hugging Face API 令牌
确保您的机器具有互联网连接以访问 Hugging Face API
如果某个特定工具失败，请尝试通过 Hugging Face 网站访问相同的数据以验证其是否存在