mcp-hfspace MCP 服务器 🤗

[!提示]

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

此项目已被官方 Hugging Face MCP 服务器 和 Gradio MCP 端点 取代。

或者您可以将 hf-mcp-server 本地作为 STDIO 服务器运行，或使用对 SSE、流式 HTTP 和流式 HTTP JSON 模式提供强大的支持。这也会运行一个本地 UI 用于选择工具和端点，并支持 ToolListChangedNotifications。

hf.co/mcp

mcp-hfspace

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

只需添加您的空间即可轻松连接到 Hugging Face Spaces - 无需大量设置！

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

Gradio MCP 支持

[!提示] Gradio 5.28 现在通过 SSE 提供了集成的 MCP 支持：https://huggingface.co/blog/gradio-mcp。检查您的目标空间是否支持 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 空间列表。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"
      ]
    }

要使用私有空间，请使用 --hf-token=hf_... 参数或 HF_TOKEN 环境变量提供您的 Hugging Face 令牌。

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

文件处理和 Claude Desktop 模式

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

还可以提供 URL 作为输入：内容将传递给空间。

有一个 "可用资源" 提示，它向 Claude 提供工作目录中的可用文件和 MIME 类型。这是目前管理文件的最佳方式。

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

我们将使用 Claude 比较由 shuttleai/shuttle-3.1-aesthetic 和 FLUX.1-schnell 创建的图像。图像保存到工作目录，并包含在 Claude 的上下文窗口中 - 这样 Claude 就可以使用其视觉功能。

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

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

使用 paligemma 找出 "test_gemma.jpg" 中是谁 -> 文本输出：david bowie

如果您要上传内容到 Claude 的上下文，请使用 Paperclip 附件按钮，否则请为服务器指定文件名以直接发送。

我们也可以提供 URL。例如：使用 paligemma 检测 https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 中的人类->图像中检测到一个人 - Taylor Swift 在舞台上。`

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

在 Claude Desktop 模式 下，音频文件保存在 WORK_DIR 中，Claude 会通知其创建。如果不在桌面模式下，文件将作为 base64 编码的资源返回给客户端（如果它支持嵌入式音频附件，则很有用）。

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

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

示例 5 - 图像转图像

在这个示例中，我们指定了 microsoft/OmniParser 要使用的文件名，并返回一个带注释的图像和 2 个单独的文本片段：描述和坐标。使用的提示是 使用 omniparser 分析 ./screenshot.png 和 使用分析结果生成一个再现该屏幕的工件。DawnC/Pawmatch 也很擅长此功能。

示例 6 - 聊天

在这个示例中，Claude 为 Qwen 设置了一些推理谜题，并询问了后续问题以澄清。

指定 API 端点

如果您需要，可以通过将端点添加到空间名来指定特定的 API 端点。因此，与其传递 Qwen/Qwen2.5-72B-Instruct，您可以使用 Qwen/Qwen2.5-72B-Instruct/model_chat。

Claude Desktop 模式

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

推荐空间

一些推荐的空间供您尝试：

图像生成

• 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 - 用于交互式狗推荐

其他功能

提示

每个空间的提示都会生成，并提供输入的机会。请记住，空间通常没有配置特别有帮助的标签等。Claude 实际上非常擅长弄清楚这一点，工具描述相当丰富（但在 Claude Desktop 中不可见）。

资源

返回 WORK_DIR 中的文件列表，并作为便利返回文件名作为 "使用文件..." 文本。如果您想将内容添加到 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/ 或 x:/temp/mcp-files/",
        "--HF_TOKEN=HF_{可选令牌}"
        "Qwen/Qwen2-72B-Instruct",
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpint"
        (... 等等)
        ]
    }
  }
}

已知问题和限制

mcp-hfspace

• 暂时不支持带有未命名参数的端点。
• 从某些复杂的 Python 类型到合适的 MCP 格式的完整转换。

Claude Desktop

• Claude Desktop 0.75 似乎不会响应 MCP 服务器的错误，而是超时。对于持续性问题，请使用 MCP 检查器以更好地诊断问题所在。如果某项功能突然停止工作，很可能是由于耗尽了您的 HuggingFace ZeroGPU 配额 - 请稍后再试，或设置自己的空间进行托管。
• Claude Desktop 似乎使用了一个硬超时值 60s，并且似乎不使用进度通知来管理 UX 或保持活动状态。如果您使用 ZeroGPU 空间，大型/重量级任务可能会超时。但请检查 WORK_DIR 以获取结果；如果已生成，MCP 服务器仍会捕获并保存结果。
• Claude Desktop 对服务器状态、日志等的报告并不理想 - 使用 @modelcontextprotocol/inspector 来帮助诊断问题。

HuggingFace Spaces

• 如果 ZeroGPU 配额或队列太长，请尝试复制空间。如果您的任务不到 60 秒，您通常可以更改 app.py 中的函数装饰器 @spaces.GPU(duration=20) 以在运行任务时请求较少的配额。
• 提供 HF_TOKEN 将使 ZeroGPU 配额适用于您的 (Pro) HF 账户
• 如果您有一个私有空间，并且有专用硬件，您的 HF_TOKEN 将直接访问该硬件 - 不适用配额。如果您正在用于任何类型的生产任务，我建议使用此方法。

第三方 MCP 服务