What is Hf Mcp Server

hf-mcp-server is a server implementation that connects to the HuggingFace API, allowing for integration with various tools and services through different transport modes.

Use cases

Use cases include deploying machine learning models for real-time inference, integrating NLP tools into applications, and providing a flexible API interface for various client applications.

How to use

To use hf-mcp-server, you can either utilize npm scripts for Docker operations or run manual Docker commands to build and run the server with specific transport types such as SSE, STDIO, or StreamableHTTP.

Key features

Key features include support for multiple transport modes (STDIO, SSE, StreamableHTTP, and StreamableHTTP in Stateless JSON Mode), a web application for tool management, and easy deployment via Docker.

Where to use

hf-mcp-server can be used in fields such as machine learning, natural language processing, and any application that requires integration with HuggingFace’s models and APIs.

Hugging Face Official MCP Server

Getting Started

This repository contains the offical Hugging Face MCP Server source. The server supports multiple deployment and configuration options, and is deployable locally as well as on your own infrastructure.

The easiest way to access Hugging Face MCP Services is via https://hf.co/mcp which offers a number of Tools, Prompts and access to Gradio Spaces which are configurable at https://hf.co/settings/mcp.

Anonymous access is supported with a default set of Tools and Prompts, or use a Hugging Face READ token to customize your settings:

For Claude Desktop (via MCP Remote) (in your mcpServers section):

"Hugging Face": {
    "command": "npx",
    "args": [
        "-y","mcp-remote",
        "https://hf.co/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
    ],
    "env": {
    "AUTH_HEADER": "Bearer <YOUR_HF_TOKEN>"
    }
}

For VSCode and Cursor (in your mcp/serversor mcpServers section respectively):

"hf-mcp-server": {
    "url": "https://hf.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }

For claude.ai (Anonymous access only - OAuth coming soon)

Enter https://hf.co/mcp from the “Add Integrations” dropdown menu.

Quick Guide (Repository Packages)

This repo contains:

• (/mcp) MCP Implementations of Hub API and Search endpoints for integration with MCP Servers.
• (/app) An MCP Server and Web Application for deploying endpoints.

MCP Server

The following transports are supported:

• STDIO
• SSE (To be deprecated, but still commonly deployed).
• StreamableHTTP
• StreamableHTTP in Stateless JSON Mode (StreamableHTTPJson)

The Web Application and HTTP Transports start by default on Port 3000.

SSE and StreamableHTTP services are available at /sse and /mcp respectively. Although though not strictly enforced by the specification this is common convention.

[!TIP]
The Web Application allows you to switch tools on and off. For STDIO, SSE and StreamableHTTP this will send a ToolListChangedNotification to the MCP Client. In StreamableHTTPJSON mode the tool will not be listed when the client next requests the tool lists.

Development

This project uses pnpm for build and development.

pnpm run clean -> clean build artifacts

pnpm run build -> build packages

pnpm run start -> start the mcp server application

pnpm run buildrun -> clean, build and start

pnpm run dev -> concurrently watch mcp and start dev server with HMR

Docker Build

Build the image:

docker build -t hf-mcp-server .

Run with default settings (Streaming HTTP JSON Mode), Dashboard on Port 3000:

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

Run STDIO MCP Server:

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

TRANSPORT can be stdio, sse, streamingHttp or streamingHttpJson (default).

Transport Endpoints

The different transport types use the following endpoints:

• SSE: /sse (with message endpoint at /message)
• Streamable HTTP: /mcp (regular or JSON mode)
• STDIO: Uses stdin/stdout directly, no HTTP endpoint

Stateful Connection Management

The sse and streamingHttp transports are both stateful - they maintain a connection with the MCP Client through an SSE connection. When using these transports, the following configuration options take effect:

Environment Variables

The server respects the following environment variables:

• TRANSPORT: The transport type to use (stdio, sse, streamableHttp, or streamableHttpJson)
• DEFAULT_HF_TOKEN: ⚠️ Requests are serviced with the HF_TOKEN received in the Authorization: Bearer header. The DEFAULT_HF_TOKEN is used if no header was sent. Only set this in Development / Test environments or for local STDIO Deployments. ⚠️
• If running with stdio transport, HF_TOKEN is used if DEFAULT_HF_TOKEN is not set.
• HF_API_TIMEOUT: Timeout for Hugging Face API requests in milliseconds (default: 12500ms / 12.5 seconds)
• USER_CONFIG_API: URL to use for User settings (defaults to Local front-end)
• MCP_STRICT_COMPLIANCE: set to True for GET 405 rejects in JSON Mode (default serves a welcome page).