hf-mcp-server packages

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.

</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:

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.

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.

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 Streamable HTTP mode
npx @llmindset/hf-mcp-server-json  # Start in Streamable HTTP (JSON RPC) 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/. The Streamable HTTP server is accessible on http://localhost:3000/mcp. See Environment Variables for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.

pnpm install

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 skills distribution in the SEP-2640 index format (a skill://index.json whose entries carry verbatim frontmatter, an optional url + digest, and an archives[] array, alongside the expanded SKILL.md/supporting-file tree and .tar.gz archives). The server walks each skill directory and exposes every file as an individual skill:// resource, supports resources/directory/read for scoped navigation, and advertises the io.modelcontextprotocol/skills extension with directoryRead: true. Defaults to /mnt/hf-skills/distribution/latest, 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