Hugging Face MCP Server: Setup, Tools and Spaces

The Hugging Face MCP server is Hugging Face's official, hosted connector at https://huggingface.co/mcp. Add it to Claude, Cursor, VS Code or another MCP client, and your assistant can search models, datasets, Spaces, papers and the docs on the Hub — and call community Gradio Spaces as tools, like an image generator or a transcriber. You don't install anything. You add one URL, sign in or pass a token, then pick extra tools on your Hugging Face settings page.

Here's the short version:

• What it is: a remote MCP server run by Hugging Face. The code is open source on GitHub under the MIT licence.
• What it does: browse and search the Hub, plus optional tools for creating repos, running Jobs and using sandboxes.
• The fun part: any Space with an MCP badge can become a tool your assistant calls directly.
• Setup: about two minutes per client. Claude Code is one command; Claude Desktop is a connector from the gallery.

If MCP itself is new to you, read what MCP is first, then come back.

What the Hugging Face MCP server does

Picture the usual routine. You need a speech-to-text model that runs on a laptop. You open the Hub, filter, sort by downloads, open five model cards, compare licences, then paste notes back into your chat.

The Hugging Face MCP server lets the assistant do that legwork inside the conversation. According to the official Hub documentation, once connected your assistant can:

• search and explore models, datasets, Spaces and papers
• search the Hugging Face documentation in plain language
• schedule and run Jobs, and use sandboxes
• run community tools through MCP-compatible Gradio apps on Spaces
• return results with metadata and links, so you can open the resource yourself

Built-in and optional tools

Most Hub tasks go through one built-in tool, hf_fs. The docs describe it as the way your assistant navigates the Hub, including semantic search over docs and Spaces.

The rest you switch on from your MCP settings page:

The "needs sign-in" column comes from the server's README, which says repository creation, Jobs, dynamic Space and sandbox tools require authentication, and from the Spaces guide, which asks for a read token to use Space tools. Without a token, the hosted server falls back to an anonymous tool set.

Hugging Face also adds experimental tools from time to time, so the list on your settings page may be longer than this table.

How to set up the Hugging Face MCP server

Every client points at the same URL. What changes is where you paste it and how you sign in.

There are two ways to sign in:

1. OAuth. Add ?login to the URL (https://huggingface.co/mcp?login), and the client opens a browser window to log in to Hugging Face.
2. A token. Pass a Hugging Face access token in an Authorization: Bearer header. A read token is enough for search and Spaces.

The settings page at huggingface.co/settings/mcp also generates a ready-to-copy snippet for each client. Hugging Face recommends using it rather than writing config by hand, and it's the safest option if a client's format has changed since this was written.

Claude Desktop and claude.ai

Hugging Face is in Claude's connector gallery. Open Settings → Connectors in Claude, find Hugging Face, add it, and sign in when prompted. There's no JSON file to edit, and Hugging Face's README gives the same steps for Claude Desktop and claude.ai.

Claude Code

One command, with OAuth:

claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"

Then start claude and finish the login. If a server needs attention later, run /mcp inside Claude Code to authenticate or check its status.

Prefer a token? Use the header flag instead:

claude mcp add hf-mcp-server -t http https://huggingface.co/mcp -H "Authorization: Bearer hf_your_token_here"

By default the server is added to the current project only. Add --scope user to make it available in every project. The Claude Code MCP docs cover scopes and claude mcp list, which shows whether each server is connected. For a deeper walkthrough of .mcp.json and scopes, see our guide to Claude Code MCP server configuration.

Cursor

Hugging Face's README has a one-click install link for Cursor. To do it by hand, add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

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

The ${env:HF_TOKEN} syntax comes from the Cursor MCP docs. It reads the token from your shell environment, so the secret never sits in a file you might commit.

VS Code and other clients

In VS Code, run MCP: Add Server from the Command Palette, choose HTTP, and enter https://huggingface.co/mcp?login. Hugging Face also offers a one-click install and lists the server in VS Code's MCP gallery.

One trap if you copy config between tools: VS Code's own config format uses a top-level servers key, while Cursor and most portable files use mcpServers. The VS Code MCP docs warn against copying between the two without checking.

Other clients work the same way. Hugging Face's docs name Codex, Zed and ChatGPT among compatible clients, and the settings page shows the snippet each one expects.

Using Gradio Spaces as MCP tools

This is where the Hugging Face MCP server stands apart from a plain search connector. Spaces host thousands of AI demos, and many are built with Gradio, which can expose an app's functions as MCP tools with names, arguments and descriptions.

To add one:

1. Browse Spaces with MCP support, or look for the grey MCP badge on any Space card.
2. Click the badge and choose Add to MCP tools.
3. Check that the Space now appears under Spaces Tools on your settings page.
4. Restart or refresh your client so it loads the new tool.

That's it. You don't edit any client config — your client already points at huggingface.co/mcp, and the server passes the new tool through.

Two settings worth knowing

Your settings page has two Space options:

• Dynamic Spaces lets the assistant find and call MCP-compatible Spaces on the fly, without you adding each one first. Handy for exploring; noisier if you want a fixed toolset.
• Remove Embedded Images strips images that Gradio Spaces return. Turn it on if your client handles images badly or you only want text. The ?no_image_content=true URL parameter does the same thing per connection.

Connecting one Space directly

You can skip the Hub server and connect a client to a single Space. Gradio apps serve MCP at the path /gradio_api/mcp/ on the Space's own address, and the app's footer has a "View API" link with a ready-made config. A private Space, or a ZeroGPU Space you want to run on your own quota, needs your Hugging Face token in the header.

Making your own Space a tool

If you build Gradio apps, the change is one argument. Install gradio[mcp], give your function type hints and a docstring, and launch with mcp_server=True. Push it to a Gradio Space and it gets the MCP badge automatically. For a server that isn't a Gradio app, you'd write it with an MCP SDK instead.

Example workflows

These are prompts adapted from Hugging Face's own examples. The exact tool calls depend on your client and the Spaces you've added.

Find a model, then test it

A realistic loop: ask for candidate models, ask the assistant to compare their model cards on size and licence, then look for a Space that runs the top pick. If that Space has an MCP badge, add it and try it on your own input — without leaving the chat.

Chain two Spaces

Hugging Face's guide shows a video made in Claude Code by chaining a video-generation Space with a text-to-speech Space. The same pattern works for any pair: generate an image, then send it to an upscaler or a captioning Space. Each step is a separate tool call, so check the output before the next one.

Tokens, quotas and limits

A few things catch people out.

Use the narrowest token that works. For search and Spaces, a read token is enough. Hugging Face also supports fine-grained tokens scoped to specific permissions. Only give write access if you plan to use Contribute Repos, and remember that a write token in an agent's hands can create repos under your name.

Keep tokens out of committed files. A token pasted into .mcp.json or .cursor/mcp.json ends up in Git if that file is in your repo. Use OAuth, environment variables or user-level config instead. Our guide to MCP security risks covers this and prompt injection from tool results.

GPU Spaces spend your quota. Many image and video Spaces run on ZeroGPU, which gives each account a daily GPU quota that depends on account type. When your assistant calls a ZeroGPU Space, the time comes out of your quota. Signed-out use gets the smallest allowance; paid Hugging Face accounts get more. Check that page for the current allowances rather than relying on numbers you saw elsewhere.

Spaces can be slow or down. Community Spaces sleep, queue and change. A tool that worked last week may time out today. If a Space matters to your workflow, duplicate it into your own account.

Results are pointers, not verdicts. Download counts and search rank don't tell you whether a model fits your data or your licence needs. Open the model card before you build on it.

When the problem isn't the MCP server

The Hugging Face MCP server is great at one job: getting your assistant to the right model, dataset or Space. It doesn't turn a Space you found into something you keep running in your own setup, alongside the rest of your tools.

That gap — seeing a working AI app and not being able to run it yourself — is what Taku is built for. It mirrors an AI app or workflow someone already got working into a desktop workspace where you can run it, edit it and save it as your own. Taku is in Beta, and the Mac app is available now.

Key points:

• The official server lives at https://huggingface.co/mcp; add ?login for OAuth, or send a token in an Authorization header.
• hf_fs handles most search and browsing; repo, Jobs, sandbox and Spaces tools need you signed in.
• Any Space with an MCP badge can become a tool with one click on your settings page.
• ZeroGPU Spaces draw on your daily GPU quota, so heavy image or video use has limits.

For more servers worth pairing with it, see our list of the best MCP servers.

FAQ

Is the Hugging Face MCP server free?

Hugging Face's docs don't list a separate price for the server. You connect with your Hugging Face account, or without one for the anonymous tool set. Costs come from what you run through it: GPU-backed Spaces draw on your ZeroGPU quota, which is larger on paid Hugging Face accounts. Check Hugging Face's own pages for current plan details.

Do I need a Hugging Face token?

Not to connect: the hosted server accepts token-less requests and gives them an anonymous tool set. You do need to sign in, by OAuth or a token, for Spaces tools, repo creation, Jobs and sandboxes.

What's the Hugging Face MCP server URL?

https://huggingface.co/mcp. Add ?login to the end if your client should sign in through the browser.

Can I run the Hugging Face MCP server locally?

Yes. The GitHub repo publishes npm packages and a Docker image that run the server over STDIO or HTTP on your machine. Most people should use the hosted URL.

Why doesn't my new Space show up as a tool?

Restart or refresh your client after adding it. Then check the Space is listed under Spaces Tools on your settings page, and that your client is signed in — the anonymous tool set doesn't include Spaces.

Is "huggingface mcp" the same as a Gradio MCP server?

Not quite. The Hugging Face MCP server is one hosted server for the whole Hub. A Gradio MCP server is a single app that exposes its own functions. The Hub server can pass Gradio Spaces through to your client, so you usually only need the one connection.