项目简介

Hugging Face MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端应用。它集成了对 Hugging Face Hub 的多种访问能力，以标准化的 MCP 工具形式提供给支持 MCP 协议的 LLM 客户端使用。

主要功能点

模型搜索 (Model Search): 查找 Hugging Face Hub 上的机器学习模型。
模型详情 (Model Detail): 获取 Hugging Face Hub 上特定模型的详细信息。
数据集搜索 (Dataset Search): 查找 Hugging Face Hub 上的机器学习数据集。
数据集详情 (Dataset Detail): 获取 Hugging Face Hub 上特定数据集的详细信息。
研究论文搜索 (Paper Search): 查找 Hugging Face Hub 上与机器学习相关的研究论文。
Space 复制 (Duplicate Space): 复制 Hugging Face Hub 上的 Space 应用（需要提供认证信息）。
支持多种传输协议，包括标准输入/输出 (STDIO)、Server-Sent Events (SSE) 和 Streamable HTTP (支持常规模式和无状态 JSON 模式)。
可选的 Web 应用界面，用于查看服务器状态和管理工具启用状态。

安装步骤

该项目使用 'pnpm' 作为包管理器。

克隆仓库:

git clone https://github.com/evalstate/hf-mcp-server.git
cd hf-mcp-server

安装依赖:
```
pnpm install
```
构建项目:
```
pnpm run build
```
这将生成可执行文件。
运行服务器: 根据需要的传输协议运行相应的脚本：
- STDIO 模式: 'pnpm run start:stdio'
- SSE 模式: 'pnpm run start:sse'
- Streamable HTTP 模式: 'pnpm run start:streamingHttp'
- Streamable HTTP JSON 模式: 'pnpm run start:streamingHttpJson'

或者使用 Docker 运行：

构建 Docker 镜像:

docker build -t hf-mcp-server .

运行 Docker 容器:

默认 (Streamable HTTP JSON 模式，端口 3000):

docker run --rm -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

STDIO 模式:

docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

可以通过设置 'TRANSPORT' 环境变量选择 'stdio', 'sse', 'streamableHttp', 或 'streamableHttpJson'。推荐在非 STDIO 模式下通过 HTTP 'Authorization: Bearer' 头传递 HF Token，但也可以设置 'DEFAULT_HF_TOKEN' 环境变量作为备用（仅建议用于开发/测试环境或本地部署）。

服务器配置（供 MCP 客户端参考）

MCP 客户端需要知道如何启动 MCP 服务器进程并与其通信。以下是配置信息示例结构及其参数说明，供 MCP 客户端配置时参考：

{
  // MCP服务器的唯一标识符
  "server name": "@huggingface/mcp-services",

  // 关于该服务器的友好描述
  "description": "Hugging Face Hub MCP Server 提供对HF资源的访问工具",

  // 用于启动MCP服务器进程的命令。
  // 例如，如果构建后生成Node.js脚本，可能是 'node'；如果使用Docker，可能是 'docker'。
  "command": "例如：node 或 docker",

  // 传递给 command 的参数列表。
  // 这些参数决定了服务器的启动方式和配置。
  "args": [
    "启动脚本路径或docker镜像名。例如：dist/app/server/stdio.js 或 hf-mcp-server",
    "可选的命令行参数，例如：--port 3000",
    // 注意：TRANSPORT和DEFAULT_HF_TOKEN等配置通常通过环境变量设置，
    // 但如果服务器支持命令行参数，也可以在此处指定。
    // 建议通过环境变量传递敏感信息（如Token）。
  ],

  // MCP服务器期望的环境变量。
  // MCP客户端可以在启动服务器进程前设置这些变量。
  "environmentVariables": {
    // 指定MCP传输协议。必须是 'stdio', 'sse', 'streamableHttp', 或 'streamableHttpJson' 之一。
    // 这是服务器如何与客户端通信的关键配置。
    "TRANSPORT": "例如：stdio 或 streamableHttpJson",
    // 可选的Hugging Face API访问令牌。
    // 如果提供，服务器将使用此Token进行认证和提高API速率限制。
    // 推荐在非STDIO模式下通过Authorization头传递Token，此项作为备用。
    "DEFAULT_HF_TOKEN": "例如：hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    // 可选的HTTP端口号。如果TRANSPORT不是stdio，服务器将监听此端口。
    // 如果通过命令行参数指定了端口，则可以忽略此项。
    "WEB_APP_PORT": "例如：3000"
  },

  // 服务器监听的端口（仅适用于非STDIO传输）。
  // MCP客户端需要知道此端口才能连接到服务器。
  "port": 3000,

  // 使用的MCP传输协议类型。
  // 必须与 environmentVariables 中的 TRANSPORT 值匹配。
  "transport": "例如：stdio 或 streamableHttpJson"
}

请注意: 具体的 'command' 和 'args' 取决于您如何打包和运行服务器（例如，直接运行 Node.js 脚本，或使用 Docker 容器）。上述 JSON 结构是向客户端解释需要哪些信息来启动该服务器的参考，而不是直接可执行的代码。MCP 客户端需要根据实际部署方式填写这些值。

基本使用方法

一旦 MCP 服务器启动并运行，支持 MCP 协议的 LLM 客户端（例如，集成了 MCP 客户端 SDK 的应用）就可以通过配置的传输协议连接到该服务器。

连接成功后，LLM 客户端将发现服务器提供的 Hugging Face 相关工具（如 'space_search', 'model_search', 等）。LLM 客户端可以根据用户的请求，调用这些工具的 JSON-RPC 方法，并提供工具定义中所需的参数（例如，搜索工具需要 'query' 参数）。

服务器会执行相应的操作（如调用 Hugging Face API），并将结果以 JSON-RPC 响应的形式返回给客户端，客户端再将结果提供给 LLM 进行进一步处理或展示给用户。

例如，LLM 客户端可能会构建一个 JSON-RPC 请求来调用 'model_search' 工具，请求体类似：

{
  "jsonrpc": "2.0",
  "method": "tool_code/model_search", // 方法名通常包含工具标识符
  "params": {
    "query": "large language model",
    "limit": 5
  },
  "id": "request-123"
}

服务器接收、处理此请求，并返回包含搜索结果的 JSON-RPC 响应。

关键词

项目简介

主要功能点

安装步骤

服务器配置（供 MCP 客户端参考）

基本使用方法

信息