Hugging Face MCP Server

Official Hugging Face MCP server that lets AI assistants search Hub models, datasets, papers, and Spaces, and use community tools.

Description

The Hugging Face MCP Server implements the Model Context Protocol and connects MCP-capable AI assistants to the Hugging Face Hub: search models, datasets, Spaces, and research papers, query Hugging Face documentation via natural-language search, and call MCP-compatible Gradio applications (community tools) directly from the chat. The built-in hf_fs tool efficiently covers most Hub tasks, including semantic search across documents and Spaces.
Additional tools can be enabled from the MCP settings page: write access to your own repositories, sandboxes with file management, and running and managing jobs on Hugging Face infrastructure. These extended tools require signing in with a Hugging Face account.

Hugging Face runs the server as a hosted remote service at https://huggingface.co/mcp. The corresponding settings page lets you pick your client (for example Claude Code, Claude Desktop, Cursor, VS Code, Zed, Gemini CLI, or ChatGPT); the page then generates a ready-to-paste configuration. Tools with write access, sandboxes, or jobs require signing in with a Hugging Face account.

Local option

Alternatively, the open-source package @llmindset/hf-mcp-server can be run locally via npx, in either STDIO or stateless Streamable HTTP mode. A Docker image is available at ghcr.io/evalstate/hf-mcp-server. Both options are useful when traffic should not go through the hosted service.

Community Spaces as a distinguishing feature

What sets the Hugging Face MCP Server apart from most other MCP servers is its connection to community Spaces: instead of only offering a fixed set of tools, any MCP-compatible Gradio application published on the Hub can be called as an additional tool in the chat. This opens the server up to a constantly growing number of specialized tools, from image editing to text analysis to domain-specific models, without Hugging Face having to implement every single feature itself. The trade-off is that these tools aren't vetted by Hugging Face itself.

Typical use cases

The server is particularly useful for research work in the machine learning space: finding suitable pretrained models for a specific task, searching datasets by size and license, looking up recent research papers on a topic, or trying out a community tool directly without switching context to a browser. For data science teams that regularly evaluate new models, natural-language Hub search can be noticeably faster than manually clicking through the web interface.

Operating Modes and Sign-in

The server supports STDIO and Streamable HTTP with JSON at the path /mcp, and the web interface runs on port 3000 by default. Locally you start it with npx @llmindset/hf-mcp-server for STDIO or npx @llmindset/hf-mcp-server-http for HTTP, or as a Docker container from ghcr.io. With HTTP, the server validates the token through the Hugging Face whoami endpoint and expects the header Authorization: Bearer. Tools for creating repositories, for jobs, dynamic Spaces and sandboxes require authentication. A management page at /metrics shows the operation, and the timeout for API calls is 12.5 seconds by default.

Frequently asked questions

Are all community Spaces trustworthy? No, they come from third parties and aren't vetted by Hugging Face itself; it's worth checking the operator before use. Does basic usage require a Hugging Face account? No, simple Hub searches and documentation queries work without signing in. Can I use the server entirely without Hugging Face infrastructure? No, even the local option still communicates with Hugging Face infrastructure for Hub data.

Requirements

For the hosted option, an MCP client that supports remote servers (the settings page shows client-specific instructions); extended tools (write access, sandboxes, jobs) additionally require a signed-in Hugging Face account. For the local option, Node.js (npx) or Docker.

Installation instructions

The Hugging Face MCP Server connects MCP-capable assistants to the Hugging Face Hub. Setup runs through a central settings page that generates a matching configuration for your client.

Step 1: Connecting via the settings page

While signed in, open https://huggingface.co/mcp and select your MCP client (for example Claude Code, Claude Desktop, Cursor, VS Code, Zed, or Gemini CLI). The page shows client-specific instructions including a ready-to-paste configuration. After pasting it, restart the client — the server should then appear as connected.

Choosing tools

The same settings page lets you decide which tools are active beyond basic Hub navigation: write access to your own repositories, sandboxes with file management, and running and monitoring jobs on Hugging Face infrastructure. These tools require signing in and should only be enabled when actually needed.

Adding community tools (Spaces)

You can also add individual MCP-compatible Gradio Spaces as further tools. Since these come from the community rather than Hugging Face itself, it's worth briefly checking the operator and purpose of a Space before enabling it.

Step 2: Local option as an alternative

Instead of the hosted service, the server can also run locally via npx @llmindset/hf-mcp-server (STDIO) or as a Docker container (ghcr.io/evalstate/hf-mcp-server) — useful when traffic should not go through the hosted service.

bash
npx @llmindset/hf-mcp-server

Step 3: Verifying the setup

After connecting, test with a harmless task such as "Search for current image classification models" or "Find datasets about weather time series." If the assistant returns matching Hub results, the connection is set up correctly.

Common connection issues

If the server doesn't show as connected after pasting the configuration, a full client restart usually helps more than just reloading the configuration. With extended tools enabled but no valid sign-in, the client often shows an authentication error — in that case, sign in again on the settings page and regenerate the configuration.

Step 4: Checking community Spaces before use

Before enabling a community Space as an additional tool, it's worth checking its page on the Hub: usage count, last update, and comments give initial signals about quality and trustworthiness. For sensitive tasks, only Spaces with a traceable, active operator should be enabled.

Expanding tool scope gradually

Instead of enabling every extended tool right away during initial setup, a gradual approach is recommended: start with just basic Hub navigation, then deliberately unlock write access, sandboxes, or job control as the need actually arises. This keeps it clear at every point which capability was enabled for which use case, rather than starting with unnecessarily broad access from day one.

This is especially relevant on shared or organization accounts, where an overly broad initial grant can be hard to notice later.

Source: huggingface.co/docs/hub/agents-mcp, huggingface.co/mcp, and the repository github.com/huggingface/hf-mcp-server (README.md), checked on 2026-09-06.

Authentication

Basic search and documentation tools work without signing in. Extended tools (write access to repositories, sandboxes, jobs) require a signed-in Hugging Face account. HTTP clients send a Hugging Face token via the Authorization: Bearer header; the local STDIO option falls back to HF_TOKEN or DEFAULT_HF_TOKEN.

Required access permissions

Without signing in, only read-only Hub searches and documentation queries are possible. When signed in, scope depends on which tools are enabled in the MCP settings: by default only Hub navigation is active, with optional write access to your own repositories, sandboxes, or running jobs on Hugging Face infrastructure.

Transmitted or stored data

Search queries and tool parameters go to Hugging Face infrastructure and are returned to the MCP client and its language model to answer the request. When calling community Spaces as tools, requests additionally pass through the respective third-party-operated Gradio application. With write or job tools enabled, the service additionally processes content from your own Hugging Face repositories and jobs.

Security risks

Community Spaces embedded as tools come from third parties and are not vetted by Hugging Face itself; a malicious or faulty Space can return misleading results or misuse inputs. With write access enabled, an agent can modify your own repositories; with job tools enabled, it can consume compute time on your own infrastructure. Enable only the Spaces and tools you need, turn on write and job access deliberately, and treat the Hugging Face token like a password.

License and costs

License
MIT
Cost
free

The MCP server itself is free, and the source code is open source (MIT license). Tools with write access, sandboxes, or jobs require a Hugging Face account; paid Hugging Face features (such as dedicated compute for jobs) are billed independently of the MCP server.

Alternatives

Not recorded yet.

At a glance

Provider
Hugging Face
Status
Official server
Deployment
Local and remote
Current version
0.4.16
GitHub stars
317
Last reviewed
07.09.2026

Repository and documentation

Categories

Supported clients

Related guides

Guides and background related to this entry.

No related guides yet.