Hugging Face MCP Server

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.