Hugging FaceMCP Server

Released Oct 22, 2025

v0.4.20

MIT

Summary

Hugging Face's official MCP server — search the Hub's models, datasets and Spaces, read repository files, and call thousands of Gradio applications as tools from one remote endpoint.

Features

Remote streamable-HTTP endpoint at huggingface.co/mcp, with OAuth via ?login or a Bearer token
Hub repository search and detail across models, datasets and Spaces
hf_fs reads repository files without cloning
Exposes Gradio Spaces as callable tools — thousands of community apps as tool calls
Per-account tool and Space selection at huggingface.co/settings/mcp
Self-hostable over STDIO or HTTP via npm or the ghcr.io container, with a /metrics dashboard

Installation

Set up this MCP server in your favorite AI agent — copy a ready-made configuration below.

Any MCP-compatible agent

Most agents (Claude, Cursor, Windsurf, VS Code, and more) read a standard mcpServers configuration.

Open your agent's MCP configuration file.
Merge the snippet below into it.
Restart the agent — the "Hugging Face" tools will be available.

{
  "mcpServers": {
    "huggingface-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://huggingface.co/mcp?login"
      ]
    }
  }
}

Claude Code

Add the server with a single CLI command.

claude mcp add huggingface-mcp -- npx -y mcp-remote https://huggingface.co/mcp?login

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config).

{
  "mcpServers": {
    "huggingface-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://huggingface.co/mcp?login"
      ]
    }
  }
}

Cursor

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://huggingface.co/mcp?login"
  ]
}

VS Code

Or install from the VS Code MCP gallery

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://huggingface.co/mcp?login"
  ]
}

Run locally over STDIO

{
  "command": "npx",
  "args": [
    "-y",
    "@llmindset/hf-mcp-server"
  ],
  "env": {
    "HF_TOKEN": "hf_xxx"
  }
}

Container, stateless streamable HTTP JSON on port 3000

{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-p",
    "3000:3000",
    "ghcr.io/evalstate/hf-mcp-server:latest"
  ]
}

Description

This is Hugging Face's official MCP server, connecting an agent to the Hugging Face Hub and to the Gradio applications hosted on it. It runs remotely at https://huggingface.co/mcp over stateless streamable HTTP, and the same code can be run locally over STDIO.

What it reaches

The built-in tools cover Hub search and metadata — repository search and repository detail across models, datasets and Spaces — plus hf_fs, a filesystem-style tool for reading repository contents without cloning. Beyond the static set, the server can expose Gradio Spaces as callable tools, which is the part that makes it unusual: an agent gains access to thousands of community-built demos (image generation, transcription, classification) as ordinary tool calls rather than as web pages to drive.

A ?bouquet= query parameter selects which group of tools is advertised. ?bouquet=openai exposes the Hub filesystem, repository search and detail, dynamic Space, Jobs and sandbox tools; the Jobs, dynamic Space and sandbox tools require authentication. Which tools and Spaces a given account sees is configured at huggingface.co/settings/mcp, and ?no_image_content=true strips ImageContent blocks from Gradio responses for clients that cannot render them.

Authentication

Adding ?login to the endpoint runs an OAuth flow; alternatively a Hugging Face token can be sent in an Authorization: Bearer header. Anonymous use works for public read operations, while Jobs and sandbox tools require a token.

Running it yourself

The server is published on npm as @llmindset/hf-mcp-server (STDIO) and @llmindset/hf-mcp-server-http (stateless streamable HTTP JSON), and as a container at ghcr.io/evalstate/hf-mcp-server. Self-hosted deployments get a management interface at /metrics reporting server status and per-method metrics, an allowlist via MCP_ALLOWED_HOSTS, and a DISABLE_TOOLS list for hiding individual tools such as hub_repo_search or hf_fs.

The project is MIT-licensed and developed in the open at huggingface/hf-mcp-server.

Related MCP Servers

MCP: Qase MCP Server

by Qase

New

Qase test management over MCP: 36 task-oriented tools for cases, runs, results, defects and QQL search, hosted at mcp.qase.io or self-run with your own API token.

Developer Tools

MCP: Arm MCP Server

by Arm

New

Arm's official MCP server for porting and tuning software on Arm — semantic docs search, codebase migration scanning, container architecture checks and LLVM-MCA assembly analysis.

Developer Tools

MCP: AntV Chart MCP

by AntV

New

Official AntV MCP server that turns a description of your data into a rendered chart — 26 visualization types from bar and line to sankey, mind-map, fishbone and geographic maps.

Developer Tools Databases & Data

MCP: Headroom

by Headroom Labs

New

Context-compression MCP server that shrinks tool outputs, logs, files and RAG chunks before they reach the model, cutting 60-95% of tokens on JSON payloads.

Developer Tools

Browse all MCP servers →