MCP 服务器

mcp-hfspace MCP Server

将 Claude Desktop 连接到 Hugging Face Spaces，只需最少的设置，即可实现图像生成、视觉任务、文本转语音以及与 AI 模型聊天等功能。

AI内容生成

AI集成系统

访问服务器

README

mcp-hfspace MCP 服务器 🤗

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

连接到 Hugging Face Spaces，只需极少的设置 - 只需添加您的 spaces 即可开始！

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

默认设置

安装

NPM 包是 @llmindset/mcp-hfspsace。

为您的平台安装最新版本的 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 space 链接来查询图像。在这种情况下，我们指定工作目录中可用的文件名：我们不想将图像直接上传到 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 Desktop 模式_下，音频文件保存在 WORK_DIR 中，并通知 Claude 创建。如果不在桌面模式下，则该文件作为 Base64 编码的资源返回给客户端（如果它支持嵌入式音频附件，则很有用）。

语音生成

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

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

音频转录

示例 5 - 图像到图像

在此示例中，我们指定 microsoft/OmniParser 要使用的文件名，并返回一个带注释的图像和 2 个单独的文本：描述和坐标。使用的提示是 use omniparser to analyse ./screenshot.png 和 use the analysis to produce an artifact that reproduces that screen。 DawnC/Pawmatch 也擅长此操作。

Omniparser 和 Artifact

示例 6 - 聊天

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

Qwen 推理测试

指定 API 端点

如果需要，您可以通过将其添加到 spacename 来指定特定的 API 端点。因此，您可以使用 Qwen/Qwen2.5-72B-Instruct/model_chat 而不是传入 Qwen/Qwen2.5-72B-Instruct。

Claude Desktop 模式

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

其他功能

提示

为每个 Space 生成提示，并提供输入的机会。请记住，通常 Spaces 没有配置特别有用的标签等。 Claude 实际上非常擅长解决这个问题，并且工具描述非常丰富（但在 Claude Desktop 中不可见）。

资源

返回 WORK_DIR 中的文件列表，并且为了方便起见，将名称作为“使用文件...”文本返回。如果要将某些内容添加到 Claude 的上下文中，请使用纸夹 - 否则请指定 MCP 服务器的文件名。 Claude 不支持从上下文中传输资源。

私有 Spaces

HuggingFace token 支持私有 Spaces。该 Token 用于下载和保存生成的内容。

使用 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 似乎使用 60 秒的硬超时值，并且似乎没有使用进度通知来管理 UX 或保持活动状态。如果您使用的是 ZeroGPU spaces，则大型/繁重的作业可能会超时。但是，请检查 WORK_DIR 中的结果；如果生成了结果，MCP 服务器仍将捕获并保存该结果。
Claude Desktops 的服务器状态报告、日志记录等不是很好 - 使用 @modelcontextprotocol/inspector 来帮助诊断问题。

HuggingFace Spaces

如果 ZeroGPU 配额或队列太长，请尝试复制 space。如果您的作业花费的时间少于 60 秒，您通常可以在 app.py 中更改函数装饰器 @spaces.GPU(duration=20) 以在运行作业时请求更少的配额。
如果您有 HuggingFace Pro 帐户，请注意 Gradio API 不会为 ZeroGPU 作业提供额外的报价 - 您需要设置一个 X-IP-Token 标头才能实现这一点。
如果您有私有 space 和专用硬件，您的 HF_TOKEN 将使您可以直接访问该 space - 不适用配额。如果您将其用于任何类型的生产任务，我建议这样做。

第三方 MCP 服务