# Connect the Hugging Face MCP Server to Claude Code or Cursor

> Add https://huggingface.co/mcp with a read token so your agent searches models, datasets, papers and docs from the chat, and uses MCP Spaces as tools.

- Canonical: https://guides-ai.com/guides/hugging-face-mcp-server-claude-code/
- Plate 16.11 · Topic: Hugging Face (https://guides-ai.com/topics/huggingface/)
- Published: 12 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

Hugging Face runs a hosted [MCP server](/glossary/#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](https://huggingface.co/settings/tokens) and create a token with the **Read** permission, the level the [MCP docs](https://huggingface.co/docs/hub/agents-mcp) require. Keep it in your shell, not in a committed file:

```bash
export HF_TOKEN=hf_xxx
```

```powershell
$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

```bash
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):

```json
{
  "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](https://huggingface.co/settings/mcp) generates the exact one for your client.

## 4. Ask the agent to search the Hub

```text
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](/guides/hugging-face-cli-download-models/) 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](https://huggingface.co/spaces?filter=mcp-server), 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](/guides/claude-code-remote-mcp-servers/); the Cursor side: [MCP servers in Cursor](/guides/cursor-mcp-servers/).