Welcome to the official Hugging Face MCP Server 🤗. Connect your LLM to the Hugging Face Hub and thousands of Gradio AI Applications.

Follow the instructions below to get started:

Install inClaude Desktop orclaude.ai

Clickhere to add the Hugging Face connector to your account.

Alternatively, navigate tohttps://claude.ai/settings/connectors, and add "Hugging Face" from the gallery.

claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login

claude mcp add hf-mcp-server \  -t http https://huggingface.co/mcp \  -H"Authorization: Bearer <YOUR_HF_TOKEN>"

Install inVSCode

Click here to add the Hugging Face connector directly to VSCode. Alternatively, install from the gallery athttps://code.visualstudio.com/mcp:

If you prefer to configure manually or use an auth token, add the snippet below to yourmcp.json configuration:

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

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

Once installed, navigate tohttps://huggingface.co/settings/mcp to configure your Tools and Spaces.

[!TIP]Add ?no_image_content=true to the URL to remove ImageContent blocks from Gradio Servers.

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.

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.

You can run the MCP Server locally with eithernpx ordocker.

npx @llmindset/hf-mcp-server# Start in STDIO modenpx @llmindset/hf-mcp-server-http# Start in Streamable HTTP modenpx @llmindset/hf-mcp-server-json# Start in Streamable HTTP (JSON RPC) mode

To run with docker:

docker pull ghcr.io/evalstate/hf-mcp-server:latestdocker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

All commands above start the Management Web interface onhttp://localhost:3000/. The Streamable HTTP server is accessible onhttp://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.

This project usespnpm for build and development. Corepack is used to ensure everyone uses the same pnpm version (10.12.3).

# Install dependenciespnpm install# Build all packagespnpm build

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 watchmcp and start dev server with HMR

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 bestdio,sse,streamingHttp orstreamingHttpJson (default).

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

Thesse andstreamingHttp transports are bothstateful - they maintain a connection with the MCP Client through an SSE connection. When using these transports, the following configuration options take effect:

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 withstdio transport,HF_TOKEN is used ifDEFAULT_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).
• AUTHENTICATE_TOOL: whether to include anAuthenticate tool to issue an OAuth challenge when called
• SEARCH_ENABLES_FETCH: When set totrue, automatically enables thehf_doc_fetch tool wheneverhf_doc_search is enabled

Hugging Face

Byevalstate·100

Access Hugging Face models, datasets, Spaces, papers, collections via MCP.