space-doctor

Hugging Face Official MCP Server

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

Installing the MCP Server

Follow the instructions below to get started:

Click here to add the Hugging Face connector to your account.

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

Enter the command below to install in Claude Code:

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

Then start claude and follow the instructions to complete authentication.

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

Enter the command below to install in Gemini CLI:

gemini mcp add -t http huggingface https://huggingface.co/mcp?login

Then start gemini and follow the instructions to complete authentication.

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

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

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

Click here to install the Hugging Face MCP Server directly in Cursor.

If you prefer to use configure manually or specify an Authorization Token, use the snippet below:

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

Once installed, navigate to https://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.

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
• StreamableHTTP in Stateless JSON Mode (StreamableHTTPJson)

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

The StreamableHTTP service is available at /mcp. Although not strictly enforced by the specification, this is a common convention.

The public Streamable HTTP deployment serves its MCP Server Card at /mcp/server-card. The public card advertises the canonical https://huggingface.co/mcp endpoint without authentication-specific query parameters; loopback deployments and explicit non-Hugging Face hosts in MCP_ALLOWED_HOSTS advertise their own /mcp endpoint. Card responses support cache revalidation with an ETag.

The Web Application at /metrics reports server status and MCP method metrics.

The Skills tab shows process-local catalog health and live Skills activity, filtered by time window (15m/1h/24h), client name/version, method, and outcome. It separates metadata probes (skills/list, skills/get, directory reads) from successful SKILL.md and supporting-file content reads; retrieval does not prove execution or complete installation. Client names/versions are self-reported. Activity is capped at 10,000 events and 24 hours, resets on restart, and flags incomplete coverage. It is independent of LOG_SKILL_EVENTS; historical events remain in the configured dataset's skills/YYYY-MM-DD/ logs. Live activity currently covers the streamableHttpJson transport. Health polling never loads/refreshes the catalog and explicitly warns that manifest byte-size verification is not yet implemented. Skills dashboard telemetry contains no target URIs, user hashes, session IDs, or file contents.

The Management Web interface can be placed behind an optional lightweight shared-password gate using METRICS_PAGE_PASSWORD. Browser visits to / redirect to the MCP welcome page at /mcp. Tool selection is resolved independently for each request from the optional Hugging Face user configuration API and the bouquet/mix query parameters. Note to security researches and bots, this is intentionally lightweight and not considered sensitive or protected data.

Use ?bouquet=openai to expose Hub filesystem, repository search, details and creation, dynamic Space, Jobs, and sandbox tools. Repository creation, Jobs, dynamic Space, and sandbox tools require Hugging Face authentication.

Running Locally

You can run the MCP Server locally with either npx or docker.

npx @llmindset/hf-mcp-server       # Start in STDIO mode
npx @llmindset/hf-mcp-server-http  # Start in stateless Streamable HTTP JSON mode

To run with docker:

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

All commands above start the Management Web interface on http://localhost:3000/metrics. Browser visits to http://localhost:3000/ redirect to the MCP welcome page at http://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.

Development

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

For OAuth discovery, dynamic registration, or Client ID Metadata Document diagnostics, see docs/oauth-diagnostics.md and run pnpm oauth:diagnose.

Benchmark harnesses, historical results, and optimization plans are maintained in the separate hf-mcp-optimise workspace.

# Install dependencies
pnpm install

# Build all packages
pnpm build

Build Commands

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), with the dashboard at /metrics on Port 3000. HTTP clients must send a Hugging Face token in the Authorization: Bearer header:

docker run --rm -p 3000:3000 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 or streamableHttpJson (default).

Transport Endpoints

The different transport types use the fo