Hugging Face MCP server
Official MCP server: search models, datasets and Spaces and read repos, dataset rows and papers. Works without a key.
AI & machine learningGuided#mcp#models#datasets#spaces#papers#ai-agents
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Hugging Face MCP server connects an AI assistant to the Hugging Face Hub: it can search models, datasets and Spaces, read repository details and dataset schemas, browse and read files and papers through a virtual hf:// file system, and report which account it is acting as. It is hosted by Hugging Face and works without an account (anonymous, with lower rate limits). A free access token raises the limits and unlocks your private and gated repositories.
- Endpoint (Streamable HTTP):
https://huggingface.co/mcp - Login variant for clients with OAuth support:
https://huggingface.co/mcp?login - Protocol: answered both the 2026-07-28
server/discovercall and the olderinitializehandshake on 2026-11-18 (server namehuggingface.co/mcp, version 0.4.x). Sessions are optional.
Credentials (optional)
- Sign in or create a free account at https://huggingface.co/join.
- Open https://huggingface.co/settings/mcp. It generates the exact snippet for your client and lets you choose which built-in tools and community Spaces are exposed.
- For a manual token, create one at https://huggingface.co/settings/tokens (a read token is enough for everything here) and send it as
Authorization: Bearer <token>. - In this collection: paste the token into the secret variable
hfToken, then open the collection's Auth tab and switch it from No auth to Bearer token with{{hfToken}}. Leave it on No auth to stay anonymous.
Tools (checked live with tools/list on 2026-11-18)
| Tool | What it does | Main arguments |
|---|---|---|
hf_whoami | Shows the account, organizations and credential type in use (never the token) | none |
hub_repo_search | Searches models, datasets and Spaces with sorting and filters | query, repo_types, author, filters, sort, limit |
hub_repo_details | Card metadata, files, Space status, dataset configs, splits and preview rows | repo_ids (required), repo_type, operations, config, split, offset, limit |
hf_fs | Virtual file system over the Hub: ls, cat, stat, find, search, attach on hf:// URIs (models, datasets, spaces, papers, docs, collections) | operations: array of {cmd, args} (1 to 30) |
All four are annotated read-only by the server. If you add community Spaces in your MCP settings (while signed in) they appear as extra tools after login; they are not part of the anonymous list. The server also offers one MCP resource, skill://hf-cli/SKILL.md, a skill file describing the hf command line tool.
Add it to your AI client
Claude Code:
claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login
# or with a token:
claude mcp add hf-mcp-server -t http https://huggingface.co/mcp -H "Authorization: Bearer $HF_TOKEN"Claude Desktop / claude.ai: Settings > Connectors, add "Hugging Face" from the gallery (or a custom connector with the URL above).
Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"huggingface": {
"url": "https://huggingface.co/mcp",
"headers": { "Authorization": "Bearer <YOUR_HF_TOKEN>" }
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"huggingface": {
"type": "http",
"url": "https://huggingface.co/mcp",
"headers": { "Authorization": "Bearer <YOUR_HF_TOKEN>" }
}
}
}Safety
Every built-in tool is read-only, so nothing here changes a repository. The risks are about data: with a token, search results and file reads can include private repositories and gated models, and that text enters your assistant's context. Prefer a read-scoped or fine-grained token, never paste it into a shared config file, and be careful with community Spaces you add in settings: a Space is arbitrary third-party code that can run on inputs you send it.
Run order
- Start here: whoami, search, details.
- Browse with hf_fs: trending lists, a model card, a paper, files in a repo.
- Datasets: structure then preview.
- Plain HTTP: server/discover, tools/list, a tools/call and the resource read as raw JSON-RPC.
Limits
Anonymous use is rate limited and a token raises the limits; Hugging Face does not publish exact numbers for the MCP server. See https://huggingface.co/docs/hub/rate-limits.
Common errors
| What you see | Meaning | What to do |
|---|---|---|
Result with isError: true for a repo | Repo id wrong, private or gated | Check author/name; add a token with access |
JSON-RPC -32601 on prompts/list | The server has no prompts | Ignore; use tools and resources |
| HTTP 401 with a token set | Token revoked or malformed | Create a new token at hf.co/settings/tokens |
| Rate-limit text in the result | Anonymous limit reached | Add a token or wait |
Empty hf_fs result | URI is not an hf:// URI or the path does not exist | Start from hf://models/trending |
Links
- Docs: https://huggingface.co/docs/hub/hf-mcp-server
- Settings: https://huggingface.co/settings/mcp
- Source: https://github.com/evalstate/hf-mcp-server
- MCP specification: https://modelcontextprotocol.io/specification/2026-07-28
Endpoints 16
1. Start here
- MCPCheck the account in use (hf_whoami)
{{mcpUrl}}Reports whether the server sees you as anonymous or as a signed-in user, with organization memberships and the credential type; it never returns the token… - MCPSearch models (hub_repo_search)
{{mcpUrl}}Searches the Hub by keyword with a shared interface for models, datasets and Spaces. Set sort to downloads, likes, trendingScore, createdAt or lastModified,… - MCPDetails of one model (hub_repo_details)
{{mcpUrl}}Fetches the card metadata of one or more repos in a single call: author, task, library, downloads, likes, parameter count, architecture and tags. repo_ids is… - MCPFind MCP-enabled Spaces (hub_repo_search)
{{mcpUrl}}Searches Spaces tagged mcp-server by passing the tag in filters. These Gradio apps can be added as extra tools in your Hugging Face MCP settings, so this is a…
2. Browse with hf_fs
- MCPTrending models (hf_fs ls)
{{mcpUrl}}Lists today's trending models using the ls command on hf://models/trending. The result is a markdown table plus structured entries with repo id, likes,… - MCPRead a model card (hf_fs cat)
{{mcpUrl}}Reads the README of a repository as text with cat. Use --offset and --max-bytes to page through long files. When you already know an exact text file URI, go… - MCPList files of a repo (hf_fs ls)
{{mcpUrl}}Lists the top-level files and folders of a model repository. Pass --recursive or --glob to narrow it, or use find for name and path matching across the whole… - MCPDaily papers (hf_fs ls)
{{mcpUrl}}Lists the latest Hugging Face daily papers with ls on hf://papers/daily/latest. Take an id from the result and read it with cat on hf://papers/<id>/paper.md,… - MCPSearch documentation (hf_fs search)
{{mcpUrl}}Searches the Hugging Face documentation through hf://docs. Paper and docs searches need a QUERY string after the URI. The result lists matching pages that you… - MCPSeveral operations in one call
{{mcpUrl}}Shows batching: two operations, a stat on a repo and a recursive find for safetensors files, run in one tool call and come back as Operation 1 and Operation…
3. Datasets
- MCPDataset structure (hub_repo_details)
{{mcpUrl}}Returns configs, splits, sizes and column schema of a dataset via the Dataset Viewer. Do this before asking for preview rows, because dataset_preview needs a… - MCPDataset preview rows (hub_repo_details)
{{mcpUrl}}Returns a few rows of a dataset split. config and split come from the structure call, offset starts at 0 and limit defaults to 5 and is clamped between 1 and…
4. Plain HTTP and resources
- POSTserver/discover (plain HTTP)
{{mcpUrl}}One POST that returns supported protocol versions, capabilities, server instructions and version, with no handshake. The server also still accepts the older… - POSTtools/list (plain HTTP)
{{mcpUrl}}Lists the four tools with their JSON input schemas and read-only annotations. With a token, any community Spaces you enabled in your MCP settings appear here… - POSTtools/call hub_repo_search (plain HTTP)
{{mcpUrl}}Calls a tool by hand: the arguments object carries the same JSON you edit in the native requests. Useful in a script or curl to see exactly what goes over the… - MCPRead the hf-cli skill (resource)
{{mcpUrl}}Reads the one MCP resource the server publishes, a markdown skill file that teaches an agent to use the hf command line tool for downloads, uploads and repo…
API details
- Base URL
https://huggingface.co/mcp- Authentication
- A bearer token in the Authorization header
- Operations
- 16 operations on 16 pathsPOST 16
- Main resources
- 1. Start here 42. Browse with hf_fs 63. Datasets 24. Plain HTTP and resources 4
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the Hugging Face MCP server in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Hugging Face MCP server collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Check the account in use (hf_whoami)” (POST {{mcpUrl}}), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Hugging Face MCP server?
Official MCP server: search models, datasets and Spaces and read repos, dataset rows and papers. Works without a key. It is listed under AI & machine learning and has 16 endpoints.
Who publishes the Hugging Face MCP server?
It is listed from Hugging Face's public API description (an OpenAPI document), not published by Hugging Face on Swastik Codes. Anyone who controls huggingface.co can claim the profile by adding a DNS TXT record.
What is the base URL of the Hugging Face MCP server?
Requests go to https://huggingface.co/mcp. Endpoint paths are added to this base URL.
How do I authenticate with the Hugging Face MCP server?
With A bearer token in the Authorization header.
How many endpoints does the Hugging Face MCP server have?
16 operations on 16 paths (16 POST). The largest groups are 1. Start here, 2. Browse with hf_fs, 3. Datasets, 4. Plain HTTP and resources.
Is forking the Hugging Face MCP server free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.