Setting up the Hugging Face MCP Server

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.

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.

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.

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.

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.