hf

The Hugging Face MCP Server (hf-mcp-server) acts as a bridge between local MCP clients and the Hugging Face Hub, enabling you to expose HF-hosted models and tools through the MCP protocol. It supports multiple transport modes, including STDIO for local, console-driven use, and Streamable HTTP variants for HTTP-based MCP Clients. After starting the server, you can access the management web interface on http://localhost:3000 and use the /mcp endpoint for the Streamable HTTP JSON RPC mode. The server is designed to integrate with Hugging Face tools, Gradio apps, and Spaces, allowing you to route requests to HF-hosted models and share endpoints with MCP-enabled clients.

Out of the box, you can run the server in different modes via npx or Docker:

• npx @llmindset/hf-mcp-server starts the STDIO MCP server (no HTTP endpoint).
• npx @llmindset/hf-mcp-server-http starts the Streamable HTTP mode.
• npx @llmindset/hf-mcp-server-json starts the JSON-RPC Streamable HTTP mode. These modes determine how MCP Clients connect to the server and how results are returned (standard streamable HTTP vs. JSON RPC). The server can be configured to use an Authorization header with a HF token, or rely on a default token in development. You can also run the server via Docker as described in the install guide to expose the web UI on port 3000 and the /mcp endpoint for HTTP-based clients.

Prerequisites:

• Node.js and npm (or pnpm) installed, or Docker installed for containerized deployment.
• Optional: a Hugging Face account and a valid HF token if you plan to access private models or spaces.

Install via npm/npx:

1. Ensure Node.js is installed. You can verify with: node -v npm -v

2. Install and run the MCP server using npx (STDIO mode): npx @llmindset/hf-mcp-server

3. To run the Streamable HTTP (HTTP) mode, use: npx @llmindset/hf-mcp-server-http

4. To run the Streamable HTTP (JSON RPC) mode, use: npx @llmindset/hf-mcp-server-json

Install via Docker:

1. Pull the latest image: docker pull ghcr.io/evalstate/hf-mcp-server:latest

2. Run the image with default settings (Streaming HTTP JSON Mode) and expose the web interface: docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

3. For STDIO MCP Server in Docker, set TRANSPORT=stdio and expose the port: docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=<YOUR_TOKEN> ghcr.io/evalstate/hf-mcp-server:latest

Notes:

• The MCP web UI is available at http://localhost:3000/.
• The Streamable HTTP server is available at http://localhost:3000/mcp (for JSON or non-JSON modes depending on setup).
• If you are behind a firewall or reverse proxy, ensure ports and HTTP headers are configured accordingly.

Environment variables and configuration tips:

• TRANSPORT: Choose 'stdio', 'streamableHttp', or 'streamableHttpJson' to select the transport type. The default is usually Streamable HTTP JSON mode in Docker.
• DEFAULT_HF_TOKEN: Use this in development or local STDIO deployments to simulate authentication if you don’t send an Authorization header. Do not expose this in production.
• In streamableHttp mode, the server maintains a stateful connection with the MCP client via SSE. You may configure: MCP_CLIENT_HEARTBEAT_INTERVAL, MCP_CLIENT_CONNECTION_CHECK, MCP_CLIENT_CONNECTION_TIMEOUT, MCP_PING_ENABLED, MCP_PING_INTERVAL to tune connection health and keep-alive behavior.
• HF API timeout can be controlled with HF_API_TIMEOUT to handle slower HF responses.
• If you’re running in a container, you can map environment variables as shown in the Docker run examples to customize behavior.
• The server supports multiple transport endpoints: STDIO (stdin/stdout), Streamable HTTP at /mcp, and optional JSON-RPC mode.
• For development, you can disable image content blocks by appending no_image_content=true to Gradio URLs as described in the Quick Guide.