mcp-hfspace MCP Server 🤗

mcp-hfspace MCP 服务 🤗

提示

你可以直接在 https://hf.co/mcp 访问和配置 Hugging Face MCP 服务，包括 Gradio Spaces。

此项目已由官方 Hugging Face MCP Server 和 Gradio MCP Endpoints 取代。

你也可以在本地将 hf-mcp-server 作为 STDIO Server 运行，或使用对 SSE、Streaming HTTP 和 Streaming HTTP JSON Mode 的强大支持。它还会运行一个本地 UI，用于选择工具和端点，并支持 ToolListChangedNotifications。

hf.co/mcp

mcp-hfspace

请在此阅读介绍：llmindset.co.uk/resources/mcp-hfspace/

只需添加 Spaces 即可连接到 Hugging Face Spaces，几乎无需设置，添加后即可使用！

默认情况下，它会连接到 black-forest-labs/FLUX.1-schnell，为 Claude Desktop 提供图像生成功能。

Gradio MCP 支持

提示

Gradio 5.28 现已通过 SSE 集成 MCP 支持：https://huggingface.co/blog/gradio-mcp。请查看你的目标 Space 是否已启用 MCP！

安装

NPM 包为 @llmindset/mcp-hfspace。

为你的平台安装较新版本的 NodeJS，然后将以下内容添加到 claude_desktop_config.json 文件的 mcpServers 部分：

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace"
      ]
    }

请确保你使用的是 Claude Desktop 0.78 或更高版本。

这样即可开始使用图像生成器。

基本设置

在参数中提供 HuggingFace Spaces 列表。mcp-hfspace 会查找最合适的端点，并自动配置以供使用。下面的安装部分提供了一个 claude_desktop_config.json 示例。

默认情况下，文件上传和下载会使用当前工作目录。在 Windows 上，这是 \users\<username>\AppData\Roaming\Claude\<version.number\ 下的一个可读写文件夹；在 MacOS 上，则是只读根目录：/。

建议覆盖此设置，并指定一个工作目录，用于处理图像和其他基于文件的内容的上传和下载。请指定 --work-dir=/your_directory 参数或 MCP_HF_WORK_DIR 环境变量。

以下是一个配置示例，用于使用现代图像生成器、视觉模型和文本转语音功能，并设置工作目录：

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/evalstate/mcp-store",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ]
    }

若要使用私有 Spaces，请通过 --hf-token=hf_... 参数或 HF_TOKEN 环境变量提供 Hugging Face Token。

如有需要，可以运行多个服务实例，以使用不同的工作目录和 Token。

文件处理和 Claude Desktop 模式

默认情况下，服务以 _Claude Desktop 模式_运行。在此模式下，图像会在工具响应中返回，而其他文件会保存到工作目录，并以消息形式返回文件路径。如果使用 Claude Desktop 作为客户端，这通常能提供最佳体验。

也可以将 URL 作为输入提供：内容会传递给 Space。

有一个“可用资源”提示词，会向 Claude 提供工作目录中的可用文件及其 MIME 类型。目前这是管理文件的最佳方式。

示例 1 - 图像生成（下载图像 / Claude Vision）

我们将使用 Claude 比较由 shuttleai/shuttle-3.1-aesthetic 和 FLUX.1-schnell 生成的图像。图像会保存到工作目录中，也会包含在 Claude 的上下文窗口中，因此 Claude 可以使用其视觉能力。

示例 2 - 视觉模型（上传图像）

我们将使用 merve/paligemma2-vqav2 空间链接 来查询图像。在这种情况下，我们指定工作目录中已有的文件名：我们不想将图像直接上传到 Claude 的上下文窗口。因此，我们可以这样提示 Claude：

use paligemma to find out who is in "test_gemma.jpg" -> Text Output: david bowie

如果要将内容上传到 Claude 的上下文中，请使用回形针附件按钮；否则，请指定文件名，让服务直接发送。

我们也可以提供 URL。例如：use paligemma to detect humans in https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> One person is detected in the image - Taylor Swift on stage.

示例 3 - 文本转语音（下载音频）

在 _Claude 桌面模式_下，音频文件会保存在 WORK_DIR 中，并会通知 Claude 文件已创建。如果不处于桌面模式，文件会作为 Base64 编码资源返回给客户端（适用于支持嵌入式音频附件的客户端）。

示例 4 - 语音转文本（上传音频）

这里，我们使用 hf-audio/whisper-large-v3-turbo 转录音频，并将其提供给 Claude。

示例 5 - 图像转图像

在此示例中，我们指定要供 microsoft/OmniParser 使用的文件名，并获得一张带注释的图像，以及两段单独的文本：描述和坐标。使用的提示词是 use omniparser to analyse ./screenshot.png 和 use the analysis to produce an artifact that reproduces that screen。DawnC/Pawmatch 也很不错。

示例 6 - 聊天

在此示例中，Claude 为 Qwen 设置了多个推理谜题，并提出后续问题以进行澄清。

指定 API 端点

如有需要，可以将特定 API 端点添加到空间名称中进行指定。因此，不要传入 Qwen/Qwen2.5-72B-Instruct，而应使用 Qwen/Qwen2.5-72B-Instruct/model_chat。

Claude 桌面模式

可以通过选项 --desktop-mode=false 或环境变量 CLAUDE_DESKTOP_MODE=false 禁用此模式。在这种情况下，内容会作为嵌入式 Base64 编码资源返回。

推荐的 Spaces

推荐尝试以下 Spaces：

图像生成

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg（背景移除）
• diyism/Datou1111-shou_xin - 精美铅笔画

聊天

• Qwen/Qwen2.5-72B-Instruct
• prithivMLmods/Mistral-7B-Instruct-v0.3

文本转语音 / 音频生成

• fantaxy/Sound-AI-SFX
• parler-tts/parler_tts

语音转文本

• hf-audio/whisper-large-v3-turbo
• （openai 模型使用未命名参数，因此无法运行）

文本转音乐

• haoheliu/audioldm2-text2audio-text2music

视觉任务

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI
• DawnC/PawMatchAI/on_find_match_click - 用于交互式狗狗推荐

其他功能

提示词

系统会为每个 Space 生成提示词，并提供输入机会。请注意，Spaces 通常没有配置特别有用的标签等。Claude 实际上很擅长弄清楚这些内容，而且工具描述相当丰富（但在 Claude Desktop 中不可见）。

资源

系统会返回 WORK_DIR 中的文件列表，并方便地以“Use the file...”文本返回文件名。若要将内容添加到 Claude 的上下文中，请使用回形针；否则，请为 MCP 服务指定文件名。Claude 不支持从上下文中传输资源。

私有空间

使用 HuggingFace 令牌即可支持私有空间。该令牌用于下载和保存生成的内容。

使用 Claude Desktop

要与 Claude Desktop 配合使用，请添加服务器配置：

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

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx"
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=~/mcp-files/ or x:/temp/mcp-files/",
        "--HF_TOKEN=HF_{optional token}"
        "Qwen/Qwen2-72B-Instruct",
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpint"
        (... and so on)
        ]
    }
  }
}

已知问题和限制

mcp-hfspace

• 暂不支持包含未命名参数的端点。
• 尚未实现将某些复杂 Python 类型完整转换为合适的 MCP 格式。

Claude Desktop

• Claude Desktop 0.75 似乎不会响应 MCP 服务返回的错误，而是直接超时。若问题持续存在，请使用 MCP Inspector 深入排查原因。如果某项功能突然停止工作，可能是 HuggingFace ZeroGPU 配额已用尽——请稍后重试，或设置自己的 Space 用于托管。
• Claude Desktop 似乎使用了 60s 的硬超时值，而且似乎不会使用进度通知来管理用户体验或保持连接。如果你使用的是 ZeroGPU spaces，大型或繁重的任务可能会超时。不过，请检查 WORK_DIR 中的结果；如果 MCP 服务已生成结果，它仍会捕获并保存该结果。
• Claude Desktop 对服务器状态、日志记录等的报告并不理想——请使用 @modelcontextprotocol/inspector 帮助排查问题。

HuggingFace Spaces

• 如果 ZeroGPU 配额或排队时间过长，请尝试复制该 space。如果任务用时少于 60 秒，通常可以将 app.py 中的函数装饰器 @spaces.GPU(duration=20) 改为申请更少的配额。
• 传入 HF_TOKEN 会使 ZeroGPU 配额计入你的（Pro）HF 账户
• 如果你有私有 space 和专用硬件，HF_TOKEN 会让你直接访问它——无需配额。如果用于任何生产任务，我建议采用这种方式。

第三方 MCP 服务