Hugging Face MCP

Install dependencies

pnpm install

Installing the MCP Server

Follow the instructions below to get started:

<details> <summary>Install in <b>Claude Desktop</b> or <b>claude.ai</b></summary> <br />

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.

<img src='docs/claude-badge.png' width='50%' align='center' />

</details>

<details> <summary>Install in <b>Claude Code</b></summary> <br />

Enter the command below to install in <b>Claude Code</b>:

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>"

</details>

<details> <summary>Install in <b>Gemini CLI</b></summary> <br />

Enter the command below to install in <b>Gemini CLI</b>:

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

Then start gemini and follow the instructions to complete authentication.

There is also a HuggingFace Gemini CLI extension that bundles the MCP server with a context file and custom commands, teaching Gemini how to better use all MCP tools.

gemini extensions install https://github.com/huggingface/hf-mcp-server

Start gemini and run /mcp auth huggingface to authenticate the extension.

</details>

<details>

<summary>Install in <b>VSCode</b></summary> <br />

Click <a href="vscode:mcp/install?%7B%22name%22%3A%22huggingface%22%2C%22gallery%22%3Atrue%2C%22url%22%3A%22https%3A%2F%2Fhuggingface.co%2Fmcp%3Flogin%22%7D">here</a> to add the Hugging Face connector directly to VSCode. Alternatively, install from the gallery at https://code.visualstudio.com/mcp:

<img src='docs/vscode-badge.png' width='50%' align='center' />

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>"
    }

</details>

<details> <summary>Install in <b>Cursor</b></summary> <br />

Click <a href="https://cursor.com/en/install-mcp?name=Hugging%20Face&config=eyJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcD9sb2dpbiJ9">here</a> to install the Hugging Face MCP Server directly in <b>Cursor</b>.

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.

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), 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, streamableHttp or streamableHttpJson (default).

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.

Environment Variables

The server respects the following environment variables: - TRANSPORT: The transport type to use (stdio, 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) - ALLOW_INTERNAL_ADDRESS_HOSTS: Optional comma-separated host allowlist to permit internal/reserved DNS resolutions for trusted domains during outbound checks (supports exact hosts and *. wildcards, for example: huggingface.co,*.hf.space). - MCP_STRICT_COMPLIANCE: set to True for GET 405 rejects in JSON Mode (default serves a welcome page). - AUTHENTICATE_TOOL: whether to include an Authenticate tool to issue an OAuth challenge when called - SEARCH_ENABLES_FETCH: When set to true, automatically enables the hf_doc_fetch tool whenever hf_doc_search is enabled - PROXY_TOOLS_CSV: Optional CSV that defines Streamable HTTP proxy tool sources (see below). - GRADIO_SKIP_INITIALIZE: When set to true, Gradio MCP calls skip the initialize handshake and issue tools/call directly. - HF_SKILLS_DIR: Local directory containing a prebuilt Agent Skills distribution (index.json plus referenced SKILL.md and .tar.gz files). Defaults to /mnt/hf-skills/distribution/latest, which is intended for a Hugging Face Space volume mounted from hf://buckets/huggingface/skills.

To expose the shared Hugging Face skills catalog from a Space, mount the bucket and keep HF_SKILLS_DIR pointed at its latest distribution directory:

hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro
hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest

Developing OpenAI Apps SDK Components

To build and test the Apps SDK component, run

cd packages/app
npm run dev:widget

Then open http://localhost:5173/gradio-widget-dev.html. This will bring up a browser with HMR where you can send Structured Content to the components for testing.

Transport Endpoints

The different transport types use the following endpoints: - Streamable HTTP: /mcp (regular or JSON mode) - STDIO: Uses stdin/stdout directly, no HTTP endpoint