HF MCP Server

A Model Context Protocol server that gives Claude (and any MCP-compatible client) direct access to the Hugging Face Hub — search models and datasets, fetch metadata, run inference on text, images and audio, all from a single conversation.

There is no official Hugging Face MCP server. This fills that gap.

What you can do

Ask Claude things like:

• "Find the top 5 trending text-generation models on Hugging Face"

• "Compare gpt2 and distilgpt2 — which has more downloads and likes?"

• "What does the README of meta-llama/Llama-2-7b say about usage?"

• "Is cardiffnlp/twitter-roberta-base-sentiment-latest ready for inference?"

• "Classify the sentiment of: I absolutely loved this film"

• "What's in this image?" (with an image URL)

• "Transcribe this audio file" (with an audio URL or local path)

Related MCP server: Hugging Face MCP Server

Tools

Requirements

• Python 3.11+

• A Hugging Face account and access token (free tier works for most tools; generate_text requires Pro/credits)

• Claude Desktop

Installation

# 1. Clone the repo
git clone https://github.com/YOUR_USERNAME/hf-mcp-server.git
cd hf-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set your Hugging Face token
cp .env.example .env
# Edit .env and replace the placeholder with your real token

Configuration

Edit .env:

HF_TOKEN=hf_your_token_here
LOG_LEVEL=INFO

Get your token at huggingface.co/settings/tokens. A Read token is enough for all tools.

Connect to Claude Desktop

Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the mcpServers entry (adjust the path to match your setup):

{
  "mcpServers": {
    "huggingface": {
      "command": "/absolute/path/to/hf-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/hf-mcp-server/main.py"]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "huggingface": {
      "command": "C:\\Users\\YourName\\Projects\\hf-mcp-server\\venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourName\\Projects\\hf-mcp-server\\main.py"]
    }
  }
}

Restart Claude Desktop. You should see the Hugging Face tools available in the toolbar.

Running the tests

pytest tests/ -v

All tests mock the HF API — no network calls, no token needed.

Architecture

hf-mcp-server/
├── main.py                  # FastMCP server — 12 tools defined with @mcp.tool()
├── config.py                # Environment variables and constants
├── src/
│   └── clients/
│       └── hf_client.py     # Async HF API wrapper
│           ├── HFClient     # Main client (httpx.AsyncClient)
│           ├── RateLimiter  # Sliding-window limiter (async, thread-safe)
│           └── TTLCache     # In-memory cache with TTL
└── tests/
    ├── test_hf_client.py    # Unit tests for RateLimiter and TTLCache
    └── test_tools.py        # Unit tests for all 12 MCP tools (mocked client)

Key design decisions:

• Async throughout — httpx.AsyncClient + asyncio, no blocking requests calls.

• Rate limiting — sliding window (not a fixed counter), implemented with asyncio.Lock so concurrent tool calls don't race each other.

• TTL cache — all GET metadata calls are cached for 1 hour by default. Inference and inference-status calls skip the cache.

• truststore — uses the OS native certificate store (needed on networks with TLS inspection/corporate proxies).

• Error handling — every tool catches exceptions and returns {"status": "error", "error": "..."} instead of crashing the MCP connection.

Notes

• generate_text uses Server-Sent Events streaming internally and returns the complete text when done. It requires a HF Pro account or inference credits — most text-generation models are not available on the free tier.

• run_image_inference and run_audio_inference accept both remote URLs and absolute local file paths.

• The HF Inference API routes requests through router.huggingface.co/hf-inference. Not all models are available on all providers — if you get a "Model not supported by provider" error, try a different model or check HF Inference docs.

License

MIT — see LICENSE.