hf-mcp-server packages

Hugging Face 官方 MCP 服务

欢迎使用 Hugging Face 官方 MCP 服务 🤗。将你的大模型连接到 Hugging Face Hub 和数千个 Gradio AI 应用。

安装 MCP 服务

请按照以下说明开始使用：

在 Claude Desktop 或 claude.ai 中安装

点击此处，将 Hugging Face 连接器添加到你的账户。

或者，前往 https://claude.ai/settings/connectors，并从目录中添加「Hugging Face」。

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

claude mcp add hf-mcp-server \
  -t http https://huggingface.co/mcp \
  -H "Authorization: Bearer <YOUR_HF_TOKEN>"

gemini mcp add -t http huggingface https://huggingface.co/mcp?login

在 VSCode 中安装

点击此处，将 Hugging Face 连接器直接添加到 VSCode。或者，也可以从 https://code.visualstudio.com/mcp 的目录中安装：

如果你希望手动配置或使用身份验证令牌，请将以下代码片段添加到 mcp.json 配置中：

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

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

安装后，前往 https://huggingface.co/settings/mcp 配置你的工具和 Spaces。

提示

在 URL 中添加 ?no_image_content=true，即可移除 Gradio 服务中的 ImageContent 块。

快速指南（仓库包）

此仓库包含：

• (/mcp) 用于与 MCP 服务集成的 Hub API 和搜索端点 MCP 实现。
• (/app) 用于部署端点的 MCP 服务和 Web 应用程序。

MCP 服务

支持以下传输方式：

• STDIO
• StreamableHTTP 无状态 JSON 模式（StreamableHTTPJson）

Web 应用和 HTTP 传输默认在端口 3000 上启动。

StreamableHTTP 服务可通过 /mcp 访问。虽然规范并未严格要求，但这是常见约定。

公开部署的 Streamable HTTP 服务会在 /mcp/server-card 提供 MCP Server Card。公开卡片会公布规范的 https://huggingface.co/mcp 端点，不包含特定于身份验证的查询参数；本地回环部署以及 MCP_ALLOWED_HOSTS 中明确指定的非 Hugging Face 主机，则会公布其自身的 /mcp 端点。卡片响应支持通过 ETag 重新验证缓存。

/metrics 下的 Web 应用会报告服务状态和 MCP 方法指标。

Skills 选项卡显示进程本地的目录健康状况和实时 Skills 活动，可按时间范围（15m/1h/24h）、客户端名称/版本、方法和结果筛选。它会将元数据探测（skills/list、skills/get、目录读取）与成功读取 SKILL.md 和辅助文件内容区分开来；检索并不能证明已执行或已完成安装。客户端名称/版本由客户端自行报告。活动记录最多保留 10,000 条事件和 24 小时，重启后会重置，并会标记覆盖范围不完整。此功能独立于 LOG_SKILL_EVENTS；历史事件仍会记录在已配置数据集的 skills/YYYY-MM-DD/ 日志中。目前，实时活动仅涵盖 streamableHttpJson 传输方式。健康状态轮询绝不会加载或刷新目录，并会明确警告尚未实现清单字节大小验证。Skills 仪表板遥测不包含目标 URI、用户哈希、会话 ID 或文件内容。

可使用 METRICS_PAGE_PASSWORD 为管理 Web 界面设置可选的轻量级共享密码门禁。浏览器访问 / 时会重定向到 /mcp 下的 MCP 欢迎页。每个请求都会独立根据可选的 Hugging Face 用户配置 API 以及 bouquet/mix 查询参数解析工具选择。请注意，安全研究人员和机器人：此功能有意采用轻量级设计，不应视为敏感或受保护数据。

使用 ?bouquet=openai 可启用 Hub 文件系统、仓库搜索、详情与创建、动态 Space、Jobs 和沙箱工具。创建仓库、Jobs、动态 Space 和沙箱工具需要 Hugging Face 身份验证。

本地运行

你可以通过 npx 或 docker 在本地运行 MCP 服务。

npx @llmindset/hf-mcp-server       # Start in STDIO mode
npx @llmindset/hf-mcp-server-http  # Start in stateless Streamable HTTP JSON mode

使用 docker 运行：

docker pull ghcr.io/evalstate/hf-mcp-server:latest
docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

以上所有命令都会在 http://localhost:3000/metrics 启动管理 Web 界面。浏览器访问 http://localhost:3000/ 时会重定向到 http://localhost:3000/mcp 下的 MCP 欢迎页。配置选项请参阅[环境变量](#Environment Variables)。Docker 默认使用 Streamable HTTP（JSON RPC）模式。

开发

本项目使用 pnpm 进行构建和开发。使用 Corepack 确保所有人使用相同的 pnpm 版本（10.12.3）。

有关 OAuth 发现、动态注册或 Client ID Metadata Document 诊断的信息，请参阅 docs/oauth-diagnostics.md，并运行 pnpm oauth:diagnose。

基准测试工具、历史结果和优化计划由单独的 hf-mcp-optimise 工作区维护。

# Install dependencies
pnpm install

# Build all packages
pnpm build

构建命令

pnpm run clean -> 清理构建产物

pnpm run build -> 构建软件包

pnpm run start -> 启动 MCP 服务应用

pnpm run buildrun -> 清理、构建并启动

pnpm run dev -> 并行监视 mcp，并使用 HMR 启动开发服务器

Docker 构建

构建镜像：

docker build -t hf-mcp-server .

使用默认设置（流式 HTTP JSON 模式）运行，仪表板位于端口 3000 的 /metrics。 HTTP 客户端必须在 Authorization: Bearer 标头中发送 Hugging Face 令牌：

docker run --rm -p 3000:3000 hf-mcp-server

运行 STDIO MCP 服务：

docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

TRANSPORT 可以是 stdio 或 streamableHttpJson（默认值）。

传输端点

不同的传输类型使用以下端点：

• 无状态流式 HTTP JSON：/mcp
• 流式 HTTP JSON 的 MCP 服务卡片：/mcp/server-card
• STDIO：直接使用 stdin/stdout，不使用 HTTP 端点

环境变量

服务支持以下环境变量：

• TRANSPORT：要使用的传输类型（stdio 或 streamableHttpJson）
• DEFAULT_HF_TOKEN：本地 STDIO 部署的默认令牌。HTTP 传输不会将其用作没有 Authorization: Bearer 标头的请求的备用令牌。
• 如果使用 stdio 传输，且未设置 DEFAULT_HF_TOKEN，则使用 HF_TOKEN。
• MCP_ALLOWED_HOSTS：MCP 和 API 路由的额外 Host 允许列表，以逗号分隔。始终允许环回主机 localhost,127.0.0.1,::1。可使用确切的主机名或以通配符开头的条目，例如 *.example.com。
• HF_API_TIMEOUT：Hugging Face API 请求超时时间，单位为毫秒（默认值：12500ms / 12.5 秒）
• USER_CONFIG_API：可选 URL，用于提供 tools/list 返回的按用户划分的发现投影，其中包括已配置的 Spaces。这些设置控制要公布哪些已部署工具，而不决定是否可以执行对已知工具的直接 tools/call。生成的 Gradio 别名仍使用已配置的 Space 映射。未设置时，将使用不可变的内置默认值。
• ALLOW_INTERNAL_ADDRESS_HOSTS：可选的逗号分隔主机允许列表，用于允许受信任域名在出站检查期间解析到内部／保留 DNS 地址（支持确切主机名和 *. 通配符，例如：huggingface.co,*.hf.space）。
• MCP_STRICT_COMPLIANCE：设为 True 时，在 JSON Mode 下对 GET 请求返回 405 拒绝响应（默认显示欢迎页）。
• MCP_STRICT_TOKEN：设为 true 时，在构建任何服务实例之前，对没有令牌的 Streamable HTTP 连接返回 401。默认情况下（未设置或设为其他值），保持当前行为：无令牌请求继续使用匿名工具集。提供的令牌必须通过 whoami 验证：无效令牌返回 401；验证不可用（包括网络错误和上游故障）时返回 503，且不会允许请求继续。在严格模式关闭时，除 401 以外的验证失败仍保持现有的开放失败行为。
• DISABLE_TOOLS：可选的逗号分隔工具名称，用于从 tools/list 中隐藏这些工具，并在调用时拒绝请求，例如 hub_repo_search,hf_fs。被拒绝的调用仍会作为错误显示在 MCP 仪表板的工具调用统计中。
• DEFINITION_TAGS：设为 off 可禁用定义标签、标签检查及相关缓存提示。符合条件的 HTTP 请求默认启用；参见定义标签。
• DEFINITION_TAGS_TTL_MS：符合条件的工具列表和发现结果的缓存提示 TTL（默认值：300000；允许设为 0）。缓存范围始终为私有。
• DEFINITION_TAGS_SALT：可选的全局部署标签盐值。更改后会使已知标签失效；所有副本应使用相同的值。
• DEFINITION_TAGS_TEST：设为 true 可启用仪表板的 Caching 标签页以及 /api/definition-tags 下的运行时盐值／统计数据控制项。生产环境中应保持禁用。控制项按进程生效，且仅在配置了 METRICS_PAGE_PASSWORD 时受保护。
• PROXY_TOOLS_CSV：可选的 CSV 文件，用于定义 Streamable HTTP 代理工具来源（见下文）。
• PROXY_TOKEN：可选令牌，仅用于启动时发现 PROXY_TOOLS_CSV 架构的身份验证。
• GRADIO_SKIP_INITIALIZE：设为 true 时，Gradio MCP 调用会跳过 initialize 握手，直接发出 tools/call。
• METRICS_PAGE_PASSWORD：可选的共享密码，用于保护 /metrics 下的管理 Web 界面及其 /api/* 端点。未设置或为空时，该界面仍为公开状态。此密码不会保护 /mcp 或 /mcp/server-card。
• HF_SKILLS_DIR：包含预构建 SEP-2640 skills 快照的本地目录：skills.json 保存每项 skill 的 uri、完整 frontmatter 及按文件列出的 {uri,digest} 资源清单，旁边则是展开后的 skill 目录。在 HTTP 传输上，服务会验证每个原始 SHA-256 摘要，并检查实际的 SKILL.md frontmatter，然后将所有文件原子性地保留在内存中。每项 skill 最多包含 512 个文件和 16 MiB 原始内容，其中包括 SKILL.md 及嵌套／共享文件；超过任一限制的快照都会被拒绝，且不会替换上次验证通过的快照。目录读取会包含空目录。快照的有效期为三小时；快照过期后，请求仍使用上次有效的快照，同时在后台加载并验证新快照；刷新失败时会保留已验证的快照，并延迟五分钟后重试。HTTP 服务实现了 skills/list、skills/get、resources/read 和可选的 resources/directory/read；仅在有可用的有效快照时，才会公布 io.modelcontextprotocol/skills，并设置 directoryRead: true。长期运行的 STDIO 传输不会公开 Skills。默认目录为 /mnt/hf-skills/distribution/latest，适用于从 hf://buckets/huggingface/skills 挂载 Hugging Face Space 卷的场景。
• LOG_SKILL_EVENTS：当配置了 LOGGING_DATASET_ID 和日志令牌时，启用 SEP-2640 Skills 探测的历史产品使用情况日志记录（默认值：true）。事件写入 skills/YYYY-MM-DD/ 下，与工具查询分开，并包含客户端／协议关联信息、成功状态、耗时、游标是否存在、结果总数，以及针对特定 get／read 操作请求的 skill:// URI。不会记录游标值、frontmatter、资源内容、响应正文和错误消息。
• SHUTDOWN_GRACE_MS：在 SIGTERM／SIGINT 时优雅关闭的最长时间（默认值：25000）。服务最多会排空正在处理的 HTTP 请求 min(5s, grace/3)，然后刷新缓冲的数据集日志，最后退出。请将其设为低于平台的停止超时时间。
• RUNTIME_METRICS_LOG_INTERVAL_MS：写入 runtime_sample 记录的间隔，记录事件循环利用率、CPU、事件循环延迟、内存、连接重用情况及 X-Forwarded-For 跳数，并写入 System 数据集流（默认值：60000；设为 0 可禁用）。需要启用系统事件日志记录。相同数据也会实时显示在仪表板的 Process runtime 卡片中。

可选管理界面密码

将 METRICS_PAGE_PASSWORD 设置为非空值，即可为管理 Web 界面及其 API 端点启用轻量级的共享密码验证：

• 浏览器访问 / 时会重定向到 /mcp。在密码验证通过前，访问 /metrics 会重定向到 /metrics/login。
• 登录成功后会重定向回 /metrics。
• 登录成功后会存储一个经过签名、有效期为 30 天的 HttpOnly、SameSite=Lax Cookie。HTTPS 请求还会添加 Secure Cookie 属性。
• /api/transport、/api/sessions、/api/transport-metrics 和 /api/skills-metrics 需要 Cookie 或有效的抓取工具凭据。
• /mcp 和公开的 /mcp/server-card 不受影响。

此功能仅用于阻止随意浏览。它没有用户、角色、速率限制或审计记录，不能替代真正的身份验证、HTTPS，也不能替代平台／反向代理层的访问控制。 如果 HTTPS 在反向代理处终止，代理必须将 X-Forwarded-Proto 覆盖为实际的客户端协议，以便应用正确设置 Cookie 的 Secure 属性。

对于 Hugging Face Space，请在 Space 设置中将其配置为 Space secret。GitHub Actions secret 不会由此仓库的工作流自动传递给正在运行的 Space。使用 Hugging Face CLI 时，对应的命令为：

hf spaces secrets add <org>/<space> -s METRICS_PAGE_PASSWORD='<shared-password>'

自动抓取工具可以通过请求头发送密码：

curl --fail-with-body --silent --show-error \
  -H "X-Metrics-Password: ${METRICS_PAGE_PASSWORD}" \
  https://your-space.hf.space/api/transport-metrics

对于简单的 URL 任务，也可以使用经过 URL 编码的查询参数：

curl --fail-with-body --silent --show-error --get \
  --data-urlencode "metrics_password=${METRICS_PAGE_PASSWORD}" \
  https://your-space.hf.space/api/transport-metrics

请尽可能使用请求头。即使应用本身不会记录凭据，反向代理或访问日志、监控系统、Shell 进程列表和浏览器历史记录仍可能保留查询字符串中的密码。

要从 Space 暴露共享的 Hugging Face skills 目录，请挂载存储桶，并确保 HF_SKILLS_DIR 指向其最新的分发目录：

hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro
hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest

代理工具（通过 CSV 使用 Streamable HTTP）

启动时，可以将 PROXY_TOOLS_CSV 设置为 HTTPS URL 或 本地文件路径，以加载代理工具定义。 如果这些代理服务需要身份验证，请设置 PROXY_TOKEN。启动时发现代理 Schema 不会使用用户令牌、默认令牌或日志记录令牌。 服务器会在启动时对每个 MCP 端点各获取一次，执行 initialize + tools/list（超时时间为 10s），并注册返回的所有工具。 如果某个来源加载失败或未返回工具，则会跳过该来源（不会导致启动失败）。

CSV 格式

tool_name,url,response_type
papers,https://evalstate-hf-papers.hf.space/mcp,SSE
news,https://example.com/mcp,JSON

• tool_name：对于单工具上游服务，这是本地工具名称；如果上游服务公开多个工具，则这是代理来源的标识符。
• url：Streamable HTTP MCP 端点。
• response_type：用于向后兼容的字段；SSE 和 JSON 均可接受。代理调用仍可使用上游 Streamable HTTP 响应，而此服务器始终向客户端返回直接的 JSON-RPC 响应。

工具命名

工具命名取决于上游 MCP 端点返回的工具数量：

• 上游只有一个工具：公开的工具名称为 CSV 第一列中的名称。
• 上游有多个工具：公开的工具名称为上游工具名称。

如果公开的代理工具名称与已注册工具冲突，则会跳过该代理工具并记录警告。

你可以在 bouquet 或 mix 中包含这些工具名称，通过 tools/list 将其公开。 使用 bouquet=proxy 或 mix=proxy 可公开从 PROXY_TOOLS_CSV 加载的所有代理工具（以及基础内置工具）。直接调用已知的、通过启动配置的代理工具不依赖此发现选项。

Dynamic Space 健康检查

monitor/distribution/bin/monitor.py --check 是针对由 DYNAMIC_SPACE_DATA 配置的目录执行的只读 CSV 健康检查。它会检查 Hub 运行时状态以及每个可运行 Space 的 Gradio MCP schema，但绝不会调用 工具、重启 Space 或创建 PR。在本地运行：

pnpm health:dynamic-spaces

它使用 Python 3 和标准库。目录 URL 必须公开。对于私有 Space 的元数据和 schema 请求，它会先使用 HF_TOKEN，再使用 DEFAULT_HF_TOKEN。根据 Hub 元数据，休眠中的 Space 会被视为可接受；除非设置了 HEALTH_PROBE_SLEEPING=true，否则不会唤醒它们。

关于八小时修复计划和只读仪表板，请参阅 monitor/README.md。 Bucket 会保留报告和原子账本。 HF_TOKEN（若未设置则回退到 DEFAULT_HF_TOKEN）是用于健康读取、重启和创建 PR 的父级 Hub 凭据；设置后，两种修复操作都会启用。RESPONSES_API_KEY（或作为后备的 OPENAI_API_KEY）是 Doctor 模型凭据。若设置了 MONITOR_HF_TOKEN，它是一个单独的只读令牌，仅传递给 Doctor。对于公开的只读监控，请省略 HF_TOKEN。作业日志会为每个 Space 输出一行状态，并附上最终摘要。

退出代码 0 表示所有 Space 都健康，1 表示至少有一个 Space 不健康或状态降级。目录或 配置无效时，退出代码为 2。可选的调整变量包括 HEALTH_TIMEOUT_SECONDS、 HEALTH_ATTEMPTS、HEALTH_RETRY_DELAY_SECONDS 和 HEALTH_PROBE_SLEEPING。有关重试和手动重置策略，请参阅 monitor/README.md。