hf-mcp-server packages

What is hf-mcp-server?

hf-mcp-server is the official Hugging Face MCP server that connects LLMs to the Hugging Face Hub and thousands of Gradio AI applications. It provides MCP implementations of Hub API and search endpoints, enabling AI assistants to interact with Hugging Face resources.

How to use hf-mcp-server?

Install via one-click links for Claude Desktop/Web, VSCode, or Cursor, or use CLI commands for Claude Code (claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login) and Gemini CLI (gemini mcp add -t http huggingface https://huggingface.co/mcp?login). Run locally with npx @llmindset/hf-mcp-server (STDIO), npx @llmindset/hf-mcp-server-http (StreamableHTTP), or via Docker. Configure tokens via environment variables like DEFAULT_HF_TOKEN or HF_TOKEN.

Key features of hf-mcp-server

• Supports STDIO, StreamableHTTP, and StreamableHTTP JSON transports
• Web management interface on port 3000 for toggling tools
• Proxy tools loaded from CSV-defined MCP endpoints
• Skills directory support for shared Hugging Face skill catalogs
• Stateful connection management with configurable timeouts
• Environment variable configuration for timeouts, transport, and tool options

Use cases of hf-mcp-server

• Connect an LLM to search and retrieve models, datasets, and Spaces from the Hugging Face Hub
• Run Gradio AI applications directly through MCP tools
• Build custom AI assistants that can interact with Hugging Face APIs
• Deploy a local MCP server with proxy tools for internal workflows

FAQ from hf-mcp-server

What transports does hf-mcp-server support?

STDIO (stdin/stdout), StreamableHTTP (stateful HTTP with SSE), and StreamableHTTP JSON (stateless JSON-RPC mode).

How do I run hf-mcp-server locally?

Use npx @llmindset/hf-mcp-server for STDIO, npx @llmindset/hf-mcp-server-http for StreamableHTTP, or pull and run the Docker image from ghcr.io/evalstate/hf-mcp-server:latest.

How do I authenticate with the server?

Pass a Hugging Face token via the Authorization: Bearer header when configuring an MCP client, or set the DEFAULT_HF_TOKEN environment variable for development/STDIO use.

What environment variables control the server?

Key variables: TRANSPORT (transport mode), DEFAULT_HF_TOKEN, HF_TOKEN (STDIO fallback), HF_API_TIMEOUT, ALLOW_INTERNAL_ADDRESS_HOSTS, MCP_STRICT_COMPLIANCE, AUTHENTICATE_TOOL, SEARCH_ENABLES_FETCH, PROXY_TOOLS_CSV, GRADIO_SKIP_INITIALIZE, and HF_SKILLS_DIR.

Where can I manage tools after installation?

Navigate to https://huggingface.co/settings/mcp to configure your tools and Spaces. The local web dashboard on port 3000 also allows toggling tools.