Hub documentation
Hugging Face MCP Server
Hugging Face MCP Server
The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, ChatGPT or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor, chat or CLI.
What you can do
- Search and explore Hub resources: models, datasets, Spaces, and papers.
- Search the Hugging Face documentation with natural language queries.
- Run community tools via MCP‑compatible Gradio apps hosted on Spaces.
- Bring results back into your assistant with metadata, links, and context.
Get started
Open your MCP settings while logged in.
Pick your client: select your MCP‑compatible client (for example Cursor, VS Code, Zed, Claude Desktop). The page shows client‑specific instructions and a ready‑to‑copy configuration snippet.
Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client.
The settings page generates the exact configuration your client expects. Use it rather than writing config by hand.
Using the server
After connecting, ask your assistant to use the Hugging Face tools. Example prompts:
- “Search Hugging Face models for Qwen 3 Quantizations.”
- “Find a Space that can transcribe audio files.”
- “Show datasets about weather time‑series.”
- “Create a 1024 x 1024 image of a cat ghibli style.”
- “How do I use LoRA adapters with PEFT?” (uses Documentation Semantic Search)
- “Find papers about vision-language models.”
Your assistant will call MCP tools exposed by the Hugging Face MCP Server (including Spaces you have selected, as shown in the next section) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat.
Built-in Tools
The Hugging Face MCP Server includes several built-in tools that connect your AI assistant to the Hugging Face ecosystem. You can enable or disable each tool from your MCP settings.
| Tool | Description |
|---|---|
| Spaces Semantic Search | Find the best AI Apps via natural language queries. |
| Papers Semantic Search | Find ML Research Papers via natural language queries. |
| Model Search | Search for ML models with filters for task, library, and more. |
| Dataset Search | Search for datasets with filters for author, tags, and more. |
| Documentation Semantic Search | Search the Hugging Face documentation using natural language. Great for finding guides, API references, and tutorials across all Hugging Face libraries. |
| Run and Manage Jobs | Run, monitor, and schedule jobs on Hugging Face infrastructure. |
| Hub Repository Details | Get detailed information about Models, Datasets, and Spaces. Optionally enable Include repository README files to include README content in results. |
Enable Documentation Semantic Search to let your assistant find relevant Hugging Face documentation. For example, ask “How do I fine-tune a model with PEFT?” or “What are the options for the transformers Trainer?”
Add community tools (Spaces)
You can extend your setup with MCP‑compatible Gradio Spaces built by the community:
- Explore Spaces with MCP support here.
- Add the relevant Space in your MCP settings on Hugging Face here.
Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. Please restart or refresh your client so it picks up new tools you add.
Check out our dedicated guide for Spaces as MCP servers here.
Spaces options
Your MCP settings provide several options to customize how Spaces work:
| Option | Description |
|---|---|
| Dynamic Spaces (Experimental) | Dynamically call MCP Spaces at runtime. When enabled, your assistant can discover and use MCP-compatible Spaces on-the-fly without adding them manually. |
| Remove Embedded Images | Remove embedded images generated by Gradio Spaces. Useful if your MCP client has limited image support or you want text-only responses. |
| MCP-UI Support (Experimental) | Embed Gradio Spaces directly in your mcp-ui client. This enables richer interactive experiences when your client supports it. |
Learn more
- Settings and client setup: https://huggingface.co/settings/mcp
- Changelog announcement: https://huggingface.co/changelog/hf-mcp-server
- Hugging Face MCP Server: https://huggingface.co/mcp
- Build your own MCP Server with Gradio Spaces: https://www.gradio.app/guides/building-mcp-server-with-gradio