使用说明

项目简介

mcp-hfspace 是一个基于 Model Context Protocol (MCP) 的服务器实现，它充当 MCP 客户端（如 Claude Desktop）和 Hugging Face Spaces 之间的桥梁。通过 mcp-hfspace，用户可以轻松地将 Hugging Face Spaces 中托管的各种 AI 模型（例如，图像生成、聊天、语音合成、语音识别等）集成到支持 MCP 协议的客户端应用中，扩展客户端的功能。

主要功能点

连接 Hugging Face Spaces: 允许 MCP 客户端访问和调用 Hugging Face Spaces 上托管的各种模型和服务。
资源管理: 提供对服务器工作目录中文件的资源管理能力，允许客户端访问和使用这些文件。
工具注册与调用: 将每个 Hugging Face Space 接口作为一个工具注册到 MCP 服务器，客户端可以通过标准 MCP 协议调用这些工具，利用 HF Spaces 提供的 AI 功能。
Prompt 模板: 为每个注册的工具提供 Prompt 模板，方便用户构建与 AI 模型的交互指令。
文件处理: 支持文件上传和下载，方便处理图像、音频等文件类型的数据。
Claude Desktop 兼容模式: 特别优化了与 Claude Desktop 的兼容性，支持以 Claude Desktop 友好的方式处理和返回结果，例如直接在 Claude 上显示图片或提供下载链接。
私有 Space 支持: 通过 Hugging Face Token 支持访问和使用私有的 Hugging Face Spaces。

安装步骤

推荐使用 'mcp-get' 或 'Smithery' 进行安装，也可以直接使用 'npm' 安装。

方法一：使用 mcp-get (推荐)

npx @michaellatman/mcp-get@latest install @llmindset/mcp-hfspace

方法二：使用 Smithery

npx @smithery/cli install @llmindset/mcp-hfspace --client claude

方法三：使用 npm (需要配置启动命令)

npm install @llmindset/mcp-hfspace

安装后，您需要在 MCP 客户端中配置服务器启动命令。

服务器配置 (claude_desktop_config.json 示例)

以下是配置 mcp-hfspace 服务器的 'claude_desktop_config.json' 示例，适用于 Claude Desktop 或其他 MCP 客户端。您需要根据您的实际情况修改 'command' 和 'args' 字段。

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

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx", // 启动命令，通常为 npx 或 node
      "args": [         // 启动参数
        "-y",           // (可选) 一些 npx 命令可能需要的参数
        "@llmindset/mcp-hfspace", // MCP 服务器包名
        "--work-dir=~/mcp-files/", // (可选) 工作目录，用于存放上传/下载的文件，建议设置
        "--hf-token=HF_YOUR_TOKEN", // (可选) Hugging Face Token，用于访问私有 Space，如不需要可删除此行
        "Qwen/Qwen2-72B-Instruct", // (必选) 要连接的 Hugging Face Space 名称，可以添加多个
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpoint" // (可选) 可以指定 Space 的特定 endpoint
        // ... 可以继续添加更多的 Space
      ]
    }
  }
}

配置参数说明:

'command': 启动服务器的命令，通常为 'npx' (如果使用 'mcp-get' 或 'Smithery' 安装) 或 'node' (如果直接使用 'npm install' 安装，并需要指定入口文件路径，例如 '"node"' 和 '"args": ["./node_modules/@llmindset/mcp-hfspace/dist/index.js", ...])'。
'args': 传递给服务器的参数列表，包括：
- '"-y"': (可选) 'npx' 可能需要的参数，例如自动确认安装。
- '"@llmindset/mcp-hfspace"': MCP 服务器的 npm 包名，用于 'npx' 执行。如果您使用 'npm install' 安装，并且 'command' 设置为 '"node"'，则此处应替换为服务器入口文件路径，例如 '"./node_modules/@llmindset/mcp-hfspace/dist/index.js"'。
- '"--work-dir=~/mcp-files/"': (可选但推荐) 设置服务器的工作目录，用于存储上传和下载的文件。请替换 '~/mcp-files/' 为您希望使用的实际路径。
- '"--hf-token=HF_YOUR_TOKEN"': (可选) 如果您需要访问私有的 Hugging Face Spaces，请提供您的 Hugging Face Token。请替换 'HF_YOUR_TOKEN' 为您的实际 Token，如果不需要访问私有 Space，可以删除此参数。
- '"Qwen/Qwen2-72B-Instruct"', '"black-forest-labs/FLUX.1-schnell"', '"space/example/specific-endpoint"': 必选参数，指定要连接的 Hugging Face Spaces 名称。 您可以添加一个或多个 Space 名称。服务器会将每个 Space 作为一个工具注册到 MCP 中。您可以直接填写 Space 的名称 (例如 '"Qwen/Qwen2-72B-Instruct"')，也可以指定 Space 内的特定 endpoint (例如 '"space/example/specific-endpoint"'，当 Space 提供了多个可调用的 endpoint 时)。

重要提示:

请根据您的实际安装方式和需求配置 'command' 和 'args'。
确保工作目录 ('--work-dir') 路径存在且 MCP 服务器进程有读写权限。
如果需要访问私有 Space，请务必配置正确的 Hugging Face Token。
您可以在 'args' 中添加多个 Hugging Face Space 名称，以便同时访问多个 Space 的功能。

基本使用方法

启动 MCP 客户端 (如 Claude Desktop): 启动配置了 mcp-hfspace 服务器的 MCP 客户端。
客户端连接服务器: 客户端会自动连接到 mcp-hfspace 服务器。
发现和使用工具: 客户端会列出 mcp-hfspace 服务器注册的工具，每个工具对应一个 Hugging Face Space 接口。
调用工具: 在客户端中，您可以像使用其他工具一样调用这些 HF Space 工具，例如，使用 Prompt 模板或直接调用工具并提供参数。
资源访问: 客户端可以列出和读取 mcp-hfspace 服务器工作目录中的文件资源。
文件上传/下载: 根据工具的功能，客户端可以上传文件到服务器工作目录，或下载服务器返回的文件资源。

示例使用场景:

图像生成: 使用 'black-forest-labs/FLUX.1-schnell' 或 'shuttleai/shuttle-3.1-aesthetic' 等 Space 进行图像生成，在 Claude Desktop 中直接查看生成的图片。
聊天对话: 使用 'Qwen/Qwen2-72B-Instruct' 或 'prithivMLmods/Mistral-7B-Instruct-v0.3' 等 Space 与大型语言模型进行对话。
语音转文本/文本转语音: 使用 'hf-audio/whisper-large-v3-turbo' 进行语音识别，或使用 'parler-tts/parler_tts' 进行语音合成。
视觉分析: 使用 'microsoft/OmniParser' 或 'merve/paligemma2-vqav2' 等 Space 对图像进行分析。

通过 mcp-hfspace，您可以将 Hugging Face Spaces 强大的 AI 模型能力无缝集成到您的 MCP 客户端应用中，极大地扩展了客户端的功能和应用场景。

关键词