Hugging Face MCP server for AI agents

The Hugging Face MCP Server allows you to connect AI applications like Claude to Hugging Face tools and services. It supports multiple deployment options for both local use and custom infrastructure integration.

Installation Options

Using the Official Hosted Server

The easiest way to use Hugging Face MCP services is through the official endpoint:

https://hf.co/mcp

You can configure your available tools and prompts at https://hf.co/settings/mcp. The server supports anonymous access with default tools, but using a Hugging Face READ token enables customization.

Client-Specific Setup

Claude Desktop Setup

For Claude Desktop, add this to 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>"
    }
}

VSCode/Cursor Setup

For VSCode and Cursor, add this to your mcp/servers or mcpServers section:

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

For OAuth authentication, use https://hf.co/mcp?login as the URL.

Claude.ai Setup

For claude.ai, enter https://hf.co/mcp from the "Add Integrations" dropdown menu. Note that claude.ai has limited support and only allows anonymous access.

Running Locally

You can run the server locally using either NPX or Docker.

Using NPX

Run one of the following commands based on your preferred transport mode:

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

Using Docker

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

All these commands start a management web interface at http://localhost:3000/. The Streamable HTTP server is accessible at http://localhost:3000/mcp. Docker defaults to Streamable HTTP (JSON RPC) mode.

Configuration

Transport Endpoints

The server supports various transport types:

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

Environment Variables

Key configuration options include:

Environment Variable	Description
`TRANSPORT`	Set to `stdio`, `sse`, `streamableHttp`, or `streamableHttpJson` (default)
`DEFAULT_HF_TOKEN`	Used when no Authorization header is sent (⚠️ Only use in dev/test environments)
`HF_API_TIMEOUT`	Timeout for Hugging Face API requests (default: 12500ms)
`MCP_CLIENT_HEARTBEAT_INTERVAL`	How often to check SSE connection health (default: 30000ms)
`MCP_CLIENT_CONNECTION_TIMEOUT`	Remove sessions inactive for this duration (default: 300000ms)
`MCP_PING_ENABLED`	Enable ping keep-alive for sessions (default: true)
`AUTHENTICATE_TOOL`	Whether to include an OAuth authentication tool
`SEARCH_ENABLES_FETCH`	When true, enables the `hf_doc_fetch` tool whenever search is enabled

Advanced Docker Configuration

Run with custom settings:

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

For STDIO mode:

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect