Connect the Hugging Face MCP Server to Claude Code or Cursor

Hugging Face runs a hosted MCP server at https://huggingface.co/mcp. Connected, your coding agent can search models, datasets, Spaces and papers, search the Hugging Face docs, and call community Gradio apps as tools. It is a remote streamable-HTTP server: nothing to install.

1. Create a read token

Open Settings › Access Tokens and create a token with the Read permission, the level the MCP docs require. Keep it in your shell, not in a committed file:

export HF_TOKEN=hf_xxx

$env:HF_TOKEN = "hf_xxx"

What it does: the client sends the token as a bearer header, so searches run as you and include gated repos you have accepted.

2. Add the server to Claude Code

claude mcp add --transport http huggingface https://huggingface.co/mcp --header "Authorization: Bearer $HF_TOKEN"

What it does: registers a server named huggingface in your user scope; --scope project writes it to .mcp.json for a team instead. Start claude, run /mcp: the entry reads connected and lists the tools, led by hf_fs, which lists, searches and reads Hub repos, docs and papers.

3. Or add it to Cursor via mcp.json

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "huggingface": {
      "url": "https://huggingface.co/mcp",
      "headers": { "Authorization": "Bearer ${env:HF_TOKEN}" }
    }
  }
}

What it does: Cursor connects on the next reload and lists the server under Settings › MCP. Claude Desktop, VS Code, Codex and Zed each want a different snippet; the MCP settings page generates the exact one for your client.

4. Ask the agent to search the Hub

Search Hugging Face for Qwen GGUF repos under 5 GB, sorted by downloads, and show the Q4_K_M file sizes.

What it does: the agent calls hf_fs to search hf://models, lists files in the repo it picks, and returns names, sizes and links. Other prompts that map straight to tools: “find a Space that transcribes audio”, “how do I use LoRA adapters with PEFT” (docs search), “find papers on vision-language models”. With the hf CLI installed, the agent can also download what it found.

5. Add a Space as a tool

Any public Space with the grey MCP badge can become a tool: open the MCP-ready Spaces, click the badge, choose Add to MCP tools, restart the client. Its functions appear as typed tools, so “remove the background from this image” runs a hosted model instead of a local install. Dynamic Spaces in the same settings lets the agent discover such Spaces at runtime.

Verify it worked

In Claude Code, /mcp shows huggingface as connected; in Cursor the server has a green dot. Ask “what Hugging Face tools do you have?” and the agent names hf_fs plus any Spaces you added.

If it fails: 401 Unauthorized means the token is missing or not a Read token; connection failed after editing JSON means the client was not reloaded; a quota error from a Space tool is the ZeroGPU limit for free accounts. Transport flags and scopes: remote MCP servers in Claude Code; the Cursor side: MCP servers in Cursor.