HuggingFace Space MCP Server (mcp-hfspace) 使用说明

项目简介

mcp-hfspace 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在弥合 MCP 客户端（如 Claude Desktop）和 Hugging Face Spaces 之间的鸿沟。通过 mcp-hfspace，您可以轻松地将 Hugging Face Spaces 上丰富的 AI 模型和应用作为 MCP 工具集成到您的 MCP 客户端中，扩展 LLM 应用的功能边界。

主要功能点

连接 Hugging Face Spaces: 允许用户通过简单的配置，将多个 Hugging Face Spaces 接入为 MCP 服务器的后端。
资源 (Resources) 管理: 支持 Claude Desktop 等客户端上传和下载文件资源，并提供工作目录用于文件存储和管理。
工具 (Tools) 注册与调用: 自动发现并注册 Hugging Face Spaces 中的可用 API 端点为 MCP 工具，支持 Claude 等客户端通过工具调用访问 Hugging Face Spaces 的功能，例如图像生成、文本转语音、视觉分析等。
Prompt 模板 (Prompts): 为每个 Hugging Face Space API 自动生成 Prompt 模板，方便用户在 Claude 等客户端中以自然语言指令调用工具。
Claude Desktop 模式: 针对 Claude Desktop 客户端进行了优化，默认以 Claude Desktop 友好的方式处理文件和资源，例如图片直接嵌入消息，其他文件保存到工作目录并返回文件路径。
支持多种 Hugging Face Spaces: 支持公开和私有的 Hugging Face Spaces，可以通过 Hugging Face Token 访问私有 Space。
文件处理: 支持上传 URL 或本地文件作为工具的输入，工具生成的文件可以保存到本地工作目录或作为资源返回给客户端。

安装步骤

安装 NodeJS: 确保您的系统已安装 NodeJS 运行时环境。建议使用较新版本。您可以从 NodeJS 官网下载并安装。

安装 npm 包: 打开终端或命令提示符，运行以下命令安装 '@llmindset/mcp-hfspace' npm 包：

npm install -g @llmindset/mcp-hfspace

服务器配置

要将 mcp-hfspace 配置为 MCP 服务器，您需要在 MCP 客户端（例如 Claude Desktop）的配置文件中添加服务器配置信息。以 Claude Desktop 为例，您需要编辑 'claude_desktop_config.json' 文件，该文件通常位于：

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

在 'claude_desktop_config.json' 文件中的 'mcpServers' 字段下，添加如下配置：

{
  "mcpServers": {
    "hfspace": {  // 服务器名称，可以自定义
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/path/to/your/workdir",  //  工作目录，用于存放上传下载的文件，请替换为实际路径
        "huggingface_username/space_name",   //  Hugging Face Space 的名称，例如 "evalstate/FLUX.1-schnell"
        "another_username/another_space"     //  可选：可以添加更多 Hugging Face Space 名称
      ]
    }
  }
}

配置参数说明:

'"hfspace"': 服务器名称，您可以在 Claude Desktop 中使用此名称 'mcp=hfspace' 来引用此服务器。您可以自定义名称。
'"command": "npx"': 启动服务器的命令，这里使用 'npx' 来运行 npm 包。
'"args"': 传递给 'npx' 命令的参数列表。
- '"-y"': 'npx' 参数，表示自动确认执行 npm 包。
- '"@llmindset/mcp-hfspace"': 要执行的 npm 包名称，即 mcp-hfspace 服务器。
- '"--work-dir=/path/to/your/workdir"': 工作目录参数，请务必替换 '/path/to/your/workdir' 为您本地的实际目录路径。此目录用于 mcp-hfspace 服务器存放上传和下载的文件资源。
- '"huggingface_username/space_name"': Hugging Face Space 名称，请替换 'huggingface_username/space_name' 为您想要连接的 Hugging Face Space 的名称。例如，要使用 'evalstate/FLUX.1-schnell' 这个 Space，就填写 'evalstate/FLUX.1-schnell'。您可以添加多个 Space 名称，用空格分隔。
- '"another_username/another_space"': 可选：更多 Hugging Face Space 名称。您可以根据需要添加更多 Hugging Face Space 名称。

可选配置参数:

'--hf-token=hf_xxxxx': Hugging Face Token 参数。如果您需要访问私有的 Hugging Face Space，或者希望使用 Hugging Face Pro 账户的配额，您可以通过 '--hf-token' 参数或设置 'HF_TOKEN' 环境变量来提供您的 Hugging Face Token。
'--desktop-mode=false': 禁用 Claude Desktop 模式参数。默认情况下，服务器以 Claude Desktop 模式运行。如果您使用的 MCP 客户端不是 Claude Desktop，或者希望以非 Claude Desktop 模式运行，可以添加 '--desktop-mode=false' 参数或设置 'CLAUDE_DESKTOP_MODE=false' 环境变量。非 Desktop 模式下，文件内容会以 Base64 编码的资源形式返回给客户端。

完整配置示例 (包含工作目录和 Hugging Face Space):

{
  "mcpServers": {
    "hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=~/mcp-files",  //  MacOS 用户家目录下的 mcp-files 目录作为工作目录
        "evalstate/FLUX.1-schnell",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2"
      ]
    }
  }
}

基本使用方法

启动 MCP 服务器: 配置完成后，启动您的 MCP 客户端（例如 Claude Desktop）。Claude Desktop 会自动启动并连接到您配置的 mcp-hfspace 服务器。
使用工具: 在 Claude Desktop 中，您可以使用自然语言指令来调用 Hugging Face Spaces 提供的工具。例如：
- '使用 FLUX.1-schnell 生成一张鲜花的图片' (假设您配置了 'evalstate/FLUX.1-schnell' Space)
- '用 paligemma 分析图片 "test_gemma.jpg" 里是谁' (假设您配置了 'merve/paligemma2-vqav2' Space，并且工作目录下有名为 "test_gemma.jpg" 的图片)
文件资源管理:
- 上传文件: 您可以使用 Claude Desktop 的附件上传功能上传文件到 mcp-hfspace 服务器的工作目录。
- 下载文件: 工具执行结果生成的文件会保存在 mcp-hfspace 服务器的工作目录中。Claude Desktop 在 Claude Desktop 模式下会自动感知图片等文件，并在上下文中显示。其他类型的文件，您可以通过 "Available Resources" Prompt 列出工作目录中的文件，并使用文件路径或 Resource URI 作为工具的参数。
- 查看可用资源: 您可以使用 "Available Resources" Prompt 获取工作目录中可用的文件列表和资源信息。

请参考仓库的 README 文档和示例，了解更多高级用法和支持的 Hugging Face Spaces。

关键词