# Hugging Face MCP Server [Official] [Health: Active]

**Category:** 🧮 Data Science Tools  
**Repository:** https://github.com/huggingface/hf-mcp-server  
**GitHub Stars:** 314  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hugging-face-mcp-server

## Description
Hugging Face's official MCP server. Connects AI assistants to the Hugging Face Hub to search models, datasets, Spaces, papers and documentation, run Jobs and sandboxes, and call MCP-enabled Gradio Spaces. Hosted at huggingface.co/mcp; sign in for your own settings and tools.

## Tools
Capabilities this server exposes over MCP:

- **hf_whoami** — Inspect the current Hugging Face authentication context, including the account, visible organization memberships, and credential access details. Read-only and never returns credential values.
- **hub_repo_search** — Search and list Hugging Face models, datasets and Spaces (sort by downloads, likes, trending) with a shared query interface. You can target models, datasets, spaces, or aggregate across multiple repo types in one call. Include links to repositories in your response.
- **hub_repo_details** — Get details for one or more Hugging Face repos (model, dataset, or space): card metadata, license, downloads, files, Space hardware/status, dataset configs, splits, columns and preview rows. Auto-detects type unless specified. For datasets, use operations: overview, dataset_structure, dataset_preview. Use dataset_structure first to discover configs, splits, sizes, and schema. Use dataset_preview only when config and split are known, unless the dataset has a single config/split.
- **hf_fs** — When to use: Hugging Face Hub models, datasets, Spaces, collections, papers, daily papers, today's trending models, current paper leaderboard, docs; list and read repository files, model and dataset cards (README, license).

Examples:
  {"operations":[{"cmd":"ls","args":["hf://models/trending","--limit","10"]}]}
  {"operations":[{"cmd":"ls","args":["hf://papers/trending"]}]}
  {"operations":[{"cmd":"ls","args":["hf://papers/daily/latest"]}]}
  {"operations":[{"cmd":"cat","args":["hf://papers/2501.00001/paper.md"]}]}
  {"operations":[{"cmd":"search","args":["hf://models","--tag","base_model:finetune:org/repo"]}]}

Use hf_fs for Hugging Face Hub filesystem operations. Call it with operations, an array of {cmd, args} items; multiple operations may be submitted together.

Usage:
  {"operations":[{"cmd":"ls","args":["hf://models/org/repo"]}]}

Grammar; each string below is one args array item:
  ls     URI [--recursive] [--glob GLOB] [--type TYPE] [--sort SORT] [--limit N]
  cat    URI [--offset N] [--max-bytes N]
  attach URI [--max-bytes N]
  stat   URI
  find   URI [--name GLOB] [--path GLOB] [--type TYPE] [--limit N]
  search URI [QUERY] [--type TYPE] [--sort SORT] [--tag TAG] [--kind mcp] [--limit N]

COMMAND = ls|cat|attach|stat|find|search.
TYPE = file|dir|repo|bucket|collection|paper|link.
SORT = createdAt|downloads|likes|lastModified|likes30d|trendingScore|mainSize|id|trending|upvotes.
URI is a canonical hf:// URI. QUERY and GLOB are each one string.

Use search for resource discovery, not repository-content search; ls for a known directory, find for recursive file discovery by name/path (not file contents), stat for filesystem metadata or an uncertain target type, cat for text contents, and attach for a complete JPEG, PNG, or WebP image. When the request gives an exact text-file URI, use cat directly; do not add ls or stat first. stat does not read the contents of JSON, Markdown, or other text files.

Search scopes: hf://models[/OWNER], hf://datasets[/OWNER], hf://spaces[/OWNER], hf://collections[/OWNER], hf://papers, and hf://docs[/...]. Repository and repository-file scopes are not supported: search a resource root or owner scope to discover resources; use find for file discovery within a repository or cat for a known text file. Paper and documentation search require QUERY. --tag filters models, datasets, and Spaces by Hub tag (repeatable; all must match) and applies only to hf://models|datasets|spaces[/OWNER]; omit QUERY when the tag already identifies the target, because QUERY also filters repository names. Derived models carry base_model:ID and base_model:RELATION:ID tags, where RELATION is finetune, adapter, merge, or quantized. --kind applies only to hf://spaces[/OWNER]; the only valid --kind value is mcp, which selects MCP Spaces. Tag families are documented at hf://README.md.
Use ls hf://models/trending, hf://datasets/trending, hf://spaces/trending, or hf://papers/trending for trending listings.
hf://papers/ID is a paper directory, not paper text. Use cat hf://papers/ID/paper.md for paper text and cat hf://papers/ID/metadata.json for metadata. No preliminary listing is needed for these known paths. Use ls hf://papers/ID to discover other resources.
Omit --limit, --sort, and --type unless the request requires them. Limits and path-specific behavior are documented at hf://README.md. Issue one hf_fs call.

Links: hf://models|datasets|spaces/OWNER/NAME/PATH maps to https://huggingface.co[/datasets|/spaces]/OWNER/NAME/resolve/main/PATH (buckets: https://huggingface.co/buckets/OWNER/NAME/resolve/PATH); URL-encode each path segment. arXiv ids (for example 2502.16161) link papers, models and datasets.

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/huggingface/hf-mcp-server), copied verbatim. Run them in order; they are not an mcpServers config.

1. Add to Claude Code:

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

2. Add to Claude Code:

```sh
claude mcp add hf-mcp-server \
  -t http https://huggingface.co/mcp \
  -H "Authorization: Bearer <YOUR_HF_TOKEN>"
```

3. Add to Gemini CLI:

```sh
gemini mcp add -t http huggingface https://huggingface.co/mcp?login
```

## Documentation

## What Hugging Face MCP Server does

Hugging Face MCP Server gives MCP clients access to Hugging Face Hub resources and selected Hugging Face execution features. It can search models, datasets, Spaces, collections, papers, daily papers, and documentation; inspect repository metadata; read files from canonical `hf://` locations; and interact with MCP-enabled Gradio Spaces.

The server is useful for research and data workflows where an assistant needs to compare Hub resources, inspect model or dataset cards, identify dataset schemas, retrieve paper text, or locate files without switching between separate Hugging Face interfaces. Authenticated configurations can also expose Jobs, sandboxes, and dynamic Space tools.

## How it works

The public service is available at `https://huggingface.co/mcp`. Clients can authenticate through the hosted sign-in flow or send a Hugging Face token in an `Authorization: Bearer` header. Tool and Space exposure can be configured from Hugging Face settings, and the `bouquet` or `mix` query parameters can select tool groups for a request.

Local execution supports two transports:

- stdio, using stdin and stdout directly
- Stateless Streamable HTTP JSON, served at `/mcp`

The HTTP deployment also exposes a server card at `/mcp/server-card` and a management interface at `/metrics`. Local HTTP services use port 3000 by default. The public endpoint can include image content from Gradio results; add `?no_image_content=true` to disable those blocks.

## Setup and configuration

For a hosted connection, add `https://huggingface.co/mcp?login` through a supported client’s MCP installation flow, then complete authentication. A token-based configuration can instead point to `https://huggingface.co/mcp` and set the `Authorization` header.

Local installations can start the stdio package with `npx @llmindset/hf-mcp-server` or the HTTP package with `npx @llmindset/hf-mcp-server-http`. Docker images are available from `ghcr.io/evalstate/hf-mcp-server:latest`; the container defaults to Streamable HTTP JSON. Set `TRANSPORT=stdio` for a stdio container and provide a token through `DEFAULT_HF_TOKEN` or, for stdio, `HF_TOKEN`.

Supported configuration variables include `TRANSPORT`, `DEFAULT_HF_TOKEN`, `HF_TOKEN`, `MCP_ALLOWED_HOSTS`, `HF_API_TIMEOUT`, `USER_CONFIG_API`, `METRICS_PAGE_PASSWORD`, and `LOG_SKILL_EVENTS`. `MCP_ALLOWED_HOSTS` accepts comma-separated hostnames or leading wildcard entries. `HF_API_TIMEOUT` controls Hugging Face API request timeouts.

## Tools and capabilities

- `hf_whoami` reports the authenticated account, visible organization memberships, and credential access details without returning credential values.
- `hub_repo_search` searches models, datasets, and Spaces using shared query and sorting options, including downloads, likes, and trending signals.
- `hub_repo_details` returns repository cards, licenses, files, downloads, Space status and hardware, plus dataset configurations, splits, columns, and preview rows.
- `hf_fs` performs Hub filesystem operations such as `ls`, `cat`, `attach`, `stat`, `find`, and `search` against `hf://` URIs.

For datasets, `dataset_structure` should be used to discover configurations, splits, sizes, and schema before requesting `dataset_preview`. For papers, `hf://papers/ID/paper.md` provides paper text and `metadata.json` provides metadata. Filesystem search discovers resources; it is not a repository-content search, so use `find` for file discovery and `cat` for a known text file.

## Limitations and notes

Filesystem operations require canonical `hf://` paths and have different behavior depending on whether the target is a resource root, repository directory, paper, or document. The `--kind mcp` filter applies only to Spaces. Repository creation, Jobs, dynamic Spaces, and sandbox tools require Hugging Face authentication. The lightweight metrics password gate is intended for basic access control, not sensitive-data protection.

_Full upstream README: https://allmcps.com/mcp/hugging-face-mcp-server/readme_