Hugging Face MCP Server

什么是 Hugging Face MCP Server？

Hugging Face MCP Server 是由 Shreyas Karnik 开发的社区版 huggingface mcp server，为 Claude 等 MCP 客户端提供对 Hugging Face Hub 的只读访问：可以搜索和查看模型、数据集、Spaces、论文和合集。

它是一个小型 Python 服务器，在本地通过 stdio 运行，调用公开的 Hub API。它不是 Hugging Face 官方的 MCP 服务器；Hugging Face 自己托管的服务器位于 https://huggingface.co/mcp，下文的对比部分会介绍。

如何使用 Hugging Face MCP Server？

前置条件：

• uv 和 Python 3.13 或更高版本（项目的 pyproject.toml 要求 >=3.13）
• https://github.com/shreyaskarnik/huggingface-mcp-server 的本地克隆
• 可选：从 https://huggingface.co/settings/tokens 获取的 Hugging Face 访问令牌，设置为 HF_TOKEN

不需要 API 密钥。README 将 HF_TOKEN 列为可选项，用于获得更高的速率限制和访问私有仓库。

Smithery（Claude Desktop）

README 提供的 Claude Desktop 一步安装命令：

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

Claude Desktop

编辑 claude_desktop_config.json：

• 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"
      ],
      "env": {
        "HF_TOKEN": "your_token_here"
      }
    }
  }
}

README 中的示例运行的是 huggingface_mcp_server.py，但当前仓库里没有这个文件。服务器代码位于 src/huggingface/，pyproject.toml 定义了 huggingface 命令，Smithery 配置启动的也是这个命令，所以上面的示例运行 huggingface。保存后重启 Claude Desktop。

Claude Code

通过 stdio 注册同一个本地命令：

claude mcp add huggingface -- uv --directory /absolute/path/to/huggingface-mcp-server run huggingface

Cursor 和 VS Code

在客户端的 MCP 配置文件中使用与 Claude Desktop 条目相同的 command 和 args。如果你想在 Cursor 或 VS Code 中一键配置远程服务器，请改用官方托管服务器（见下文）。

Hugging Face MCP Server 的主要功能

• 对 Hugging Face Hub API 只读访问，不能上传、编辑或删除任何内容。
• 十个工具，覆盖模型、数据集、Spaces、论文和合集
• 自定义 hf:// URI 方案用于资源：hf://model/{model_id}、hf://dataset/{dataset_id}、hf://space/{space_id}，均以 JSON 返回
• 两个提示模板：compare-models（接收逗号分隔的 model_ids）和 summarize-paper（接收 arxiv_id，可选 detail_level，取值 brief 或 detailed）
• 无需任何配置即可使用，HF_TOKEN 为可选项
• 在本地通过 stdio 运行，采用 MIT 许可证
• 可通过 Smithery 或 uv 安装

Hugging Face MCP Server 工具

工具分为五组：

• 模型： search-models 可按关键词、作者、标签和数量过滤；get-model-info 返回单个模型的详细信息。
• 数据集： search-datasets 和 get-dataset-info 对数据集提供同样的功能。
• Spaces： search-spaces 可按 SDK 类型（如 Gradio）过滤；get-space-info 返回单个 Space 的详细信息。
• 论文： get-paper-info 按 arXiv ID 查询论文及其在 Hub 上的实现；get-daily-papers 返回每日精选论文列表。
• 合集： search-collections 和 get-collection-info 用于浏览精选合集。

这些工具都不会运行推理或生成内容，只返回 Hub 元数据。

Hugging Face MCP Server 的使用场景

• 发现模型："Search for BERT models on Hugging Face with less than 100 million parameters."
• 在模型之间做选择："Compare the Llama-3-8B and Mistral-7B models from Hugging Face." 这可以使用 compare-models 提示模板。
• 数据集调研："Find the most popular datasets for text classification on Hugging Face."
• 跟进研究动态："What are today's featured AI research papers on Hugging Face?"
• 快速阅读论文："Summarize the paper with arXiv ID 2307.09288 using the Hugging Face MCP server."
• 寻找演示："Show me the most popular Gradio spaces for image generation." 或者："Find collections created by TheBloke that include Mixtral models."

Hugging Face MCP Server 与替代方案对比

• 官方 Hugging Face MCP 服务器（https://huggingface.co/mcp，源码位于 huggingface/hf-mcp-server）。这是 Hugging Face 维护的托管服务器，通过 HTTP 连接，本地无需运行任何程序。它支持通过 ?login 登录，或使用 Authorization: Bearer <YOUR_HF_TOKEN> 请求头。工具和 Spaces 在 https://huggingface.co/settings/mcp 中选择。除了 Hub 搜索，它还能调用支持 MCP 的 Gradio Spaces，例如生成图片。官方文档提供了 Claude Desktop/claude.ai、Claude Code、Gemini CLI、VS Code 和 Cursor 的配置方法。在 Claude Code 中：

  claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login
  

  在 Cursor 或 VS Code 中使用令牌时，官方配置片段为：

  "huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
  }
  

• 本社区服务器。 它是一套固定的只读工具，运行在你自己的机器上。如果你想要一个无需登录 Hugging Face 的小型本地进程，或者需要 hf:// 资源和两个提示模板，它会比较合适。该仓库自 2025 年 3 月以来没有新的提交。

如今搜索 "hugging face mcp" 的大多数人需要的是官方托管服务器。只有在明确需要本地只读 Hub 浏览器时，才选择这个社区版本。

Hugging Face MCP Server 常见问题排查

• 服务器在 Claude Desktop 中无法启动： 查看日志 ~/Library/Logs/Claude/mcp-server-huggingface.log（macOS）或 %APPDATA%\Claude\logs\mcp-server-huggingface.log（Windows）。常见原因是让 uv run 运行仓库中不存在的 huggingface_mcp_server.py。请改为运行 huggingface，并确保 --directory 是绝对路径。
• Python 版本错误： 项目要求 Python 3.13 或更高版本。可以让 uv 安装匹配的解释器，或升级现有版本。
• 速率限制错误： README 建议添加 Hugging Face 令牌。但在当前源码中，Hub 请求通过一个不带认证头的普通 HTTP 客户端发出，因此令牌未必能提高限制。如果需要认证访问，请改用官方服务器。
• 调试工具调用： 用 MCP Inspector 运行服务器：npx @modelcontextprotocol/inspector uv --directory /path/to/huggingface-mcp-server run huggingface，然后打开它输出的 URL。
• 工具没有返回结果： 先确认网络连接正常，再到 huggingface.co 上查找同一个模型或数据集，确认它存在。