mcp-hfspace MCP 服务器🤗

在这里阅读介绍llmindset.co.uk/resources/mcp-hfspace/

只需最少的设置即可连接到Hugging Face 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 空间列表。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"
      ]
    }

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

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

文件处理和 Claude 桌面模式

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

URL 也可以作为输入提供：内容会传递到空间。

有一个“可用资源”提示，它会向 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 DawnC/Pawmatch也擅长此道。

示例 6 - 聊天

在这个例子中，克劳德为 Qwen 设置了许多推理谜题，并提出后续问题以进行澄清。

指定 API 端点

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

克劳德桌面模式

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

其他功能

提示

每个空间都会生成提示，并提供输入的机会。请记住，空间通常没有配置特别有用的标签等。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/ 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 0.75 似乎无法响应 MCP 服务器的错误，而是超时了。对于持续存在的问题，请使用 MCP 检查器来更好地诊断问题所在。如果某些功能突然停止运行，可能是由于您的 HuggingFace ZeroGPU 配额已耗尽 - 请稍后重试，或设置您自己的空间进行托管。
Claude Desktop 似乎使用 60 秒的硬超时值，并且似乎不使用进度通知来管理用户体验或保持活动状态。如果您使用 ZeroGPU 空间，大型/繁重的作业可能会超时。不过，请检查 WORK_DIR 以获取结果；如果生成了结果，MCP 服务器仍然会捕获并保存结果。
Claude Desktops 对服务器状态、日志等的报告并不是很好 - 使用@modelcontextprotocol/inspector来帮助诊断问题。

HuggingFace 空间

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

mcp-hfspace MCP Server

Integrations