# Hugging Face MCP Server

> The official Hugging Face MCP Server that connects AI assistants to the Hugging Face Hub, enabling access to models, datasets, research papers, and thousands of Gradio AI applications.

The Hugging Face MCP Server is the official open-source server that bridges AI assistants with the Hugging Face Hub ecosystem via the Model Context Protocol (MCP). Built by Hugging Face and released under the MIT License, it is actively maintained on GitHub with the latest release being v0.4.5 as of August 2026. The server is written in TypeScript and supports both STDIO and StreamableHTTP (stateless JSON mode) transports.

## What It Is

The Hugging Face MCP Server implements the Model Context Protocol — an open standard that enables AI assistants to securely connect to external data sources and tools. Through this server, LLM-powered clients can search and discover models, datasets, research papers, and Spaces (AI applications) hosted on the Hugging Face Hub. It acts as a bridge between any MCP-compatible AI client and Hugging Face's ecosystem of over 2 million models, 500,000 datasets, and 1 million applications.

## Supported Clients and Setup Path

The server is designed for quick integration with popular AI development environments. The README documents one-click or single-command installation for:

- **Claude Desktop / claude.ai** — via the Connectors gallery
- **Claude Code** — via `claude mcp add hf-mcp-server -t http https://huggingface.co/mcp`
- **Visual Studio Code** — via the MCP gallery at code.visualstudio.com/mcp
- **Cursor** — via a direct install link or manual JSON config
- **Gemini CLI** — via `gemini mcp add`
- **LM Studio** — supported client listed on the project homepage

Authentication uses a Hugging Face API token passed as a Bearer header, or via an OAuth login flow using the `?login` query parameter.

## Deployment Model

The server can be consumed in three ways:

- **Hosted endpoint** — Use `https://huggingface.co/mcp` directly; no local setup required
- **npx** — Run locally with `npx @llmindset/hf-mcp-server` (STDIO) or `npx @llmindset/hf-mcp-server-http` (HTTP)
- **Docker** — Pull `ghcr.io/evalstate/hf-mcp-server:latest` and run with configurable transport and token settings

The web application and HTTP transports start on port 3000 by default and include a management dashboard that reports server status and MCP method metrics.

## Architecture and Extensibility

The repository is organized into two main packages: `/mcp` (Hub API and search endpoint implementations) and `/app` (the MCP server and web application). Key architectural features include:

- **Proxy tools via CSV** — Load additional MCP tool definitions at startup from external Streamable HTTP endpoints by setting `PROXY_TOOLS_CSV`
- **Skills catalog** — Expose a shared Hugging Face skills catalog via `HF_SKILLS_DIR`, supporting the SEP-2640 index format and `skill://` resources
- **Tool filtering** — Disable specific tools via `DISABLE_TOOLS` environment variable
- **Per-user configuration** — Optional `USER_CONFIG_API` for per-user tool and Space selection
- **Bouquet/mix parameters** — Query parameters for dynamic tool selection per request

The server supports the `io.modelcontextprotocol/skills` extension with `directoryRead: true` for skills navigation.

## Update: v0.4.5

The latest release, v0.4.5, was published on August 1, 2026, with the repository showing active development (last push the same day). The project was created in May 2025 and has accumulated 271 stars and 84 forks on GitHub. The project homepage at `huggingface.co/mcp` serves as the primary entry point for the hosted server, with detailed client setup instructions and tool/Space configuration available at `huggingface.co/settings/mcp`.

## Features
- Connect AI assistants to Hugging Face Hub via MCP
- Search and discover models, datasets, and research papers
- Access thousands of Gradio AI applications (Spaces)
- STDIO and StreamableHTTP (stateless JSON) transport support
- Hosted endpoint at huggingface.co/mcp
- Local deployment via npx or Docker
- Management web dashboard with MCP method metrics
- Per-user tool and Space configuration
- Proxy tools via CSV for external MCP endpoints
- Skills catalog support with SEP-2640 index format
- Bearer token and OAuth login authentication
- Tool filtering via DISABLE_TOOLS environment variable
- Bouquet/mix query parameters for dynamic tool selection

## Integrations
Claude Desktop, Claude.ai, Claude Code, Visual Studio Code, Cursor, Gemini CLI, LM Studio, Codex CLI, Hugging Face Hub, Gradio, Docker

## Platforms
WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
v0.4.5

## Links
- Website: https://huggingface.co/mcp
- Documentation: https://github.com/huggingface/hf-mcp-server
- Repository: https://github.com/huggingface/hf-mcp-server
- EveryDev.ai: https://www.everydev.ai/tools/hugging-face-mcp-server