Hugging Face Official MCP Server
Welcome to the official Hugging Face MCP Server 🤗. Connect your LLM to the Hugging Face Hub and thousands of Gradio AI Applications.
Quick Guide (Repository Packages)
This repo contains:
- (
/mcp) MCP Implementations of Hub API and Search endpoints for integration with MCP Servers.
- (
/app) An MCP Server and Web Application for deploying endpoints.
MCP Server
The following transports are supported:
- STDIO
- StreamableHTTP in Stateless JSON Mode (StreamableHTTPJson)
The Web Application and HTTP Transports start by default on Port 3000.
The StreamableHTTP service is available at /mcp. Although not strictly enforced by the specification, this is a common convention.
The public Streamable HTTP deployment serves its MCP Server Card at /mcp/server-card. The public card advertises the canonical https://huggingface.co/mcp endpoint without authentication-specific query parameters; loopback deployments and explicit non-Hugging Face hosts in MCP_ALLOWED_HOSTS advertise their own /mcp endpoint. Card responses support cache revalidation with an ETag.
The Web Application at /metrics reports server status and MCP method metrics.
The Skills tab shows process-local catalog health and live Skills activity, filtered by time window (15m/1h/24h), client name/version, method, and outcome. It separates metadata probes (skills/list, skills/get, directory reads) from successful SKILL.md and supporting-file content reads; retrieval does not prove execution or complete installation. Client names/versions are self-reported. Activity is capped at 10,000 events and 24 hours, resets on restart, and flags incomplete coverage. It is independent of LOG_SKILL_EVENTS; historical events remain in the configured dataset's skills/YYYY-MM-DD/ logs. Live activity currently covers the streamableHttpJson transport. Health polling never loads/refreshes the catalog and explicitly warns that manifest byte-size verification is not yet implemented. Skills dashboard telemetry contains no target URIs, user hashes, session IDs, or file contents.
The Management Web interface can be placed behind an optional lightweight shared-password gate using METRICS_PAGE_PASSWORD. Browser visits to / redirect to the MCP welcome page at /mcp. Tool selection is resolved independently for each request from the optional Hugging Face user configuration API and the bouquet/mix query parameters. Note to security researches and bots, this is intentionally lightweight and not considered sensitive or protected data.
Use ?bouquet=openai to expose Hub filesystem, repository search, details and creation, dynamic Space, Jobs, and sandbox tools. Repository creation, Jobs, dynamic Space, and sandbox tools require Hugging Face authentication.
Running Locally
You can run the MCP Server locally with either npx or docker.
npx @llmindset/hf-mcp-server # Start in STDIO mode
npx @llmindset/hf-mcp-server-http # Start in stateless Streamable HTTP JSON mode
To run with docker:
docker pull ghcr.io/evalstate/hf-mcp-server:latest
docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest
All commands above start the Management Web interface on http://localhost:3000/metrics. Browser visits to http://localhost:3000/ redirect to the MCP welcome page at http://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.
Development
This project uses pnpm for build and development. Corepack is used to ensure everyone uses the same pnpm version (10.12.3).
For OAuth discovery, dynamic registration, or Client ID Metadata Document diagnostics, see
docs/oauth-diagnostics.md and run pnpm oauth:diagnose.
Benchmark harnesses, historical results, and optimization plans are maintained
in the separate hf-mcp-optimise workspace.
# Install dependencies
pnpm install
# Build all packages
pnpm build
Build Commands
pnpm run clean -> clean build artifacts
pnpm run build -> build packages
pnpm run start -> start the mcp server application
pnpm run buildrun -> clean, build and start
pnpm run dev -> concurrently watch mcp and start dev server with HMR
Docker Build
Build the image:
docker build -t hf-mcp-server .
Run with default settings (Streaming HTTP JSON Mode), with the dashboard at /metrics on Port 3000.
HTTP clients must send a Hugging Face token in the Authorization: Bearer header:
docker run --rm -p 3000:3000 hf-mcp-server
Run STDIO MCP Server:
docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server
TRANSPORT can be stdio or streamableHttpJson (default).
Transport Endpoints
The different transport types use the following endpoints:
- Stateless Streamable HTTP JSON:
/mcp
- MCP Server Card for Streamable HTTP JSON:
/mcp/server-card
- STDIO: Uses stdin/stdout directly, no HTTP endpoint
Environment Variables
The server respects the following environment variables:
TRANSPORT: The transport type to use (stdio or streamableHttpJson)DEFAULT_HF_TOKEN: Default token for local STDIO deployments. HTTP transports do not use this as a fallback for requests without an Authorization: Bearer header.- If running with
stdio transport, HF_TOKEN is used if DEFAULT_HF_TOKEN is not set.
MCP_ALLOWED_HOSTS: Additional comma-separated Host allowlist for MCP and API routes. Loopback hosts localhost,127.0.0.1,::1 are always allowed. Use exact hostnames or leading wildcard entries such as *.example.com.HF_API_TIMEOUT: Timeout for Hugging Face API requests in milliseconds (default: 12500ms / 12.5 seconds)USER_CONFIG_API: Optional URL for the per-user discovery projection returned by tools/list, including configured
Spaces. These settings control which deployed tools are advertised, not whether a direct tools/call to a known tool
may execute. Generated Gradio aliases still use the configured Space mapping. When unset, immutable built-in defaults
are used.ALLOW_INTERNAL_ADDRESS_HOSTS: Optional comma-separated host allowlist to permit internal/reserved DNS resolutions for trusted domains during outbound checks (supports exact hosts and *. wildcards, for example: huggingface.co,*.hf.space).MCP_STRICT_COMPLIANCE: set to True for GET 405 rejects in JSON Mode (default serves a welcome page).MCP_STRICT_TOKEN: set to true to reject token-less Streamable HTTP connections with 401 before any server instance is built. Default (unset or any other value) keeps the current behavior: token-less requests continue with the anonymous tool set. Supplied tokens must pass whoami validation: invalid tokens return 401, and unavailable validation (including network errors and upstream failures) returns 503 without allowing the request to proceed. With strict mode disabled, validation failures other than 401 retain the existing fail-open behavior.DISABLE_TOOLS: Optional comma-separated tool names to hide from tools/list and reject if called, for example hub_repo_search,hf_fs. Rejected calls remain visible as errors in the MCP dashboard tool-call statistics.DEFINITION_TAGS: Set to off to disable definition tags, tag checks, and associated cache hints. Enabled by default for eligible HTTP requests; see definition tags.DEFINITION_TAGS_TTL_MS: Cache-hint TTL for eligible tool-list and discovery results (default: 300000; 0 allowed). Cache scope is always private.DEFINITION_TAGS_SALT: Optional deploy-wide tag salt. Changing it invalidates known tags; use the same value across replicas.DEFINITION_TAGS_TEST: Set to true to enable the dashboard Caching tab and runtime salt/statistics controls under /api/definition-tags. Leave disabled in production. Controls are per-process and protected only when METRICS_PAGE_PASSWORD is configured.PROXY_TOOLS_CSV: Optional CSV that defines Streamable HTTP proxy tool sources (see below).PROXY_TOKEN: Optional token used only for startup authentication while discovering PROXY_TOOLS_CSV schemas.GRADIO_SKIP_INITIALIZE: When set to true, Gradio MCP calls skip the initialize handshake and issue tools/call directly.METRICS_PAGE_PASSWORD: Optional shared password for the Management Web interface at /metrics and its /api/* endpoints. When unset or empty, the interface remains public. This does not protect /mcp or /mcp/server-card.HF_SKILLS_DIR: Local directory containing a prebuilt SEP-2640 skills snapshot: skills.json carries each skill's uri, complete frontmatter, and per-file {uri,digest} resource manifest, alongside the expanded skill directories. On HTTP transports, the server verifies every raw SHA-256 digest and checks the actual SKILL.md frontmatter before atomically retaining all files in memory. Each skill is limited to 512 files and 16 MiB of raw content, including SKILL.md and nested/shared files; a snapshot exceeding either limit is rejected without replacing the last verified snapshot. Directory reads include empty directories. Snapshots have a three-hour freshness TTL; stale requests keep using the last valid snapshot while one background refresh is loaded and verified, and refresh failures retain that verified snapshot with a five-minute retry delay. The HTTP server implements skills/list, skills/get, resources/read, and optional resources/directory/read, and advertises io.modelcontextprotocol/skills with directoryRead: true only when a valid snapshot is available. Skills are not exposed over the long-lived STDIO transport. Defaults to /mnt/hf-skills/distribution/latest, intended for a Hugging Face Space volume mounted from hf://buckets/huggingface/skills.LOG_SKILL_EVENTS: Enables historical product-usage logging for SEP-2640 Skills probes when LOGGING_DATASET_ID and a logging token are configured (default: true). Events are written under skills/YYYY-MM-DD/, separately from tool queries, and contain client/protocol correlation, success, duration, cursor presence, aggregate result counts, and the requested skill:// URI for targeted get/read operations. Cursor values, frontmatter, resource content, response bodies, and error messages are not recorded.SHUTDOWN_GRACE_MS: Upper bound for a graceful shutdown on SIGTERM/SIGINT (default: 25000). The server drains in-flight HTTP requests for at most min(5s, grace/3), then flushes buffered dataset logs, then exits. Keep it below the platform's stop timeout.RUNTIME_METRICS_LOG_INTERVAL_MS: Interval for writing a runtime_sample record (event-loop utilisation, CPU, event-loop delay, memory, connection reuse, X-Forwarded-For hop counts) to the System dataset stream (default: 60000; 0 disables). Requires system event logging to be enabled. The same data is shown live in the dashboard's Process runtime card.
Optional Management Interface Password
Set METRICS_PAGE_PASSWORD to a non-empty value to enable a lightweight shared-password gate for the Management Web interface and its API endpoints:
- Browser visits to
/ redirect to /mcp. Visits to /metrics are redirected to /metrics/login until the password is accepted.
- A successful login redirects back to
/metrics.
- A successful login stores a signed, 30-day
HttpOnly, SameSite=Lax cookie. HTTPS requests also receive the Secure cookie attribute.
/api/transport, /api/sessions, /api/transport-metrics, and /api/skills-metrics require the cookie or a valid scraper credential./mcp and the public /mcp/server-card are not affected.
This is intended only to discourage casual browsing. It has no users, roles, rate limiting, or audit trail and is not a substitute for real authentication, HTTPS, or access control at the platform/reverse-proxy layer.
When HTTPS terminates at a reverse proxy, the proxy must overwrite X-Forwarded-Proto with the actual client protocol so the application can apply the cookie's Secure attribute correctly.
For a Hugging Face Space, configure this as a Space secret in the Space settings. A GitHub Actions secret is not automatically passed to a running Space by this repository's workflows. With the Hugging Face CLI, the equivalent command is:
hf spaces secrets add <org>/<space> -s METRICS_PAGE_PASSWORD='<shared-password>'
Automated scrapers can send the password in a header:
curl --fail-with-body --silent --show-error \
-H "X-Metrics-Password: ${METRICS_PAGE_PASSWORD}" \
https://your-space.hf.space/api/transport-metrics
For simple URL-based jobs, a URL-encoded query parameter is also accepted:
curl --fail-with-body --silent --show-error --get \
--data-urlencode "metrics_password=${METRICS_PAGE_PASSWORD}" \
https://your-space.hf.space/api/transport-metrics
Prefer the header where possible. Query-string passwords can be retained in reverse-proxy or access logs, monitoring systems, shell process listings, and browser history even though the application does not log the credential itself.
To expose the shared Hugging Face skills catalog from a Space, mount the bucket and keep HF_SKILLS_DIR pointed at its latest distribution directory:
hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro
hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest
Proxy tools (Streamable HTTP via CSV)
You can load proxy tool definitions at startup by setting PROXY_TOOLS_CSV to a HTTPS URL or a local file path.
If those proxy servers require authentication, set PROXY_TOKEN. User, default, and logging tokens are never used
for startup proxy schema discovery.
The server fetches each MCP endpoint once on startup, runs initialize + tools/list (10s timeout), and registers any tools returned.
If a source fails or returns no tools, it is skipped (no startup failure).
CSV format
tool_name,url,response_type
papers,https://evalstate-hf-papers.hf.space/mcp,SSE
news,https://example.com/mcp,JSON
tool_name: local tool name for single-tool upstreams; identifier for the proxy source when the upstream exposes
multiple tools.url: Streamable HTTP MCP endpoint.response_type: legacy compatibility field; SSE and JSON are both accepted. Proxy calls can still consume
upstream Streamable HTTP responses, while this server always returns direct JSON-RPC responses to its clients.
Tool naming
Tool naming depends on how many tools the upstream MCP endpoint returns:
- Single upstream tool: the exposed tool name is the first CSV column.
- Multiple upstream tools: the exposed tool names are the upstream tool names.
If an exposed proxy tool name collides with an already-registered tool, the proxy tool is skipped and a warning is
logged.
You can include these tool names in bouquets or mixes to advertise them through tools/list.
Use bouquet=proxy or mix=proxy to advertise all proxy tools loaded from PROXY_TOOLS_CSV (in addition to the base
built-in tools). Direct calls to a known startup-configured proxy tool do not depend on that discovery selection.
Dynamic Space health checks
monitor/distribution/bin/monitor.py --check is a read-only CSV health check for the catalog configured by
DYNAMIC_SPACE_DATA. It checks Hub runtime state and each runnable Space's Gradio MCP schema, but never invokes a
tool, restarts a Space, or opens a PR. Run it locally with:
pnpm health:dynamic-spaces
It uses Python 3 and the standard library. The catalog URL must be public. It uses HF_TOKEN, then
DEFAULT_HF_TOKEN, for private Space metadata and schema requests. Sleeping Spaces are accepted from Hub metadata
without waking them unless HEALTH_PROBE_SLEEPING=true.
For the eight-hour repair schedule and read-only dashboard, follow monitor/README.md.
The Bucket preserves reports and the atomic ledger.
HF_TOKEN (falling back to DEFAULT_HF_TOKEN) is the parent Hub credential for health reads, restarts, and
PR creation; both repair actions are enabled when it is present. RESPONSES_API_KEY (or its OPENAI_API_KEY
fallback) is the Doctor model credential. MONITOR_HF_TOKEN, if set, is a separate read-only token passed only to
the Doctor. Omit HF_TOKEN for a public read-only monitor. Job logs contain one status line per Space and a final
summary.
Exit code 0 means every Space is healthy and 1 means at least one Space is unhealthy or degraded. Invalid catalog
or configuration is reported as exit code 2. Optional tuning variables are HEALTH_TIMEOUT_SECONDS,
HEALTH_ATTEMPTS, HEALTH_RETRY_DELAY_SECONDS, and HEALTH_PROBE_SLEEPING. See
monitor/README.md for retry and manual-reset policy.