Overview

The HuggingFace Spaces MCP Server is a lightweight bridge that exposes Hugging Face Spaces apps as Model Context Protocol (MCP) tools. It enables developers to run open-source image, audio, and text models hosted as Spaces and present them to clients and agents (for example Claude Desktop) via a standardized MCP interface. This makes it easier to integrate community models into multi-model workflows, automation, or agent tooling without reimplementing each model’s HTTP surface.

By wrapping Spaces in an MCP-compatible server you get uniform discovery, invocation, and optional authentication for heterogeneous models (text generation, audio transcription, image generation, etc.). The server can be deployed locally or on a private host, supports Docker-based installation, and includes a “Claude Desktop mode” to simplify connecting the server to Claude-compatible clients.

Features

Expose Hugging Face Spaces apps as MCP tools (image, audio, text)
Automatic tool discovery and manifest generation for MCP clients
Claude Desktop mode for seamless desktop integration
Docker and docker-compose deployment for local/edge use
Configurable list of Spaces (URL, type, metadata, routing)
Basic auth / API-key support and optional CORS/TLS configuration
Health and status endpoints for monitoring
Request proxying and simple payload adaptation (JSON / multipart)
Caching and rate limiting options for Spaces backends

Installation / Configuration

Prerequisites:

Docker (or Python + virtualenv if building from source)
Optional: Hugging Face API token if you interact with private Spaces

Clone repository and run with Docker:

# Clone the repo
git clone https://github.com/evalstate/mcp-hfspace.git
cd mcp-hfspace

# Build (optional) or pull official image
docker build -t evalstate/mcp-hfspace:latest .

# Run with default config
docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e HF_API_TOKEN=${HF_API_TOKEN} \
  evalstate/mcp-hfspace:latest

Example docker-compose.yml:

version: "3.8"
services:
  mcp-hfspace:
    image: evalstate/mcp-hfspace:latest
    ports:
      - "8080:8080"
    environment:
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8080"
      HF_API_TOKEN: "${HF_API_TOKEN}"
      CLAUDE_MODE: "true"
    volumes:
      - ./config:/app/config

Example configuration file (config/spaces.yaml):

server:
  host: 0.0.0.0
  port: 8080
  claude_mode: true

spaces:
  - id: sd-image
    name: "StableDiffusionSpace"
    url: "https://huggingface.co/spaces/owner/stable-diffusion"
    type: "image-generation"
    description: "Stable Diffusion v2-like image generator"
  - id: whisper-transcribe
    name: "WhisperTranscribe"
    url: "https://huggingface.co/spaces/owner/whisper"
    type: "audio-transcription"
    description: "Open-source speech-to-text via Whisper"

After starting the container, the server will read config/spaces.yaml and register each Space as an MCP tool.

Available Resources

Common HTTP endpoints (typical paths — check your server logs/config for exact routes):

GET /health — basic health check
GET /tools — list registered MCP tools
GET /tools/:id — tool metadata and manifest
POST /tools/:id/invoke — invoke a tool (JSON body or multipart)
GET /mcp/manifest.json — high-level MCP manifest for Claude Desktop

Example: list tools with curl

curl http://localhost:8080/tools

Example: invoke an image-generation tool (JSON prompt)

curl -X POST http://localhost:8080/tools/sd-image/invoke \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A futuristic city skyline at sunset","width":512,"height":512}'

Example MCP manifest (snippet) used for Claude Desktop integration:

{
  "name": "HF Spaces MCP Server",
  "version": "1.0",
  "tools_url": "http://localhost:8080/tools",
  "claude_mode": true
}

Use Cases

Image generation pipeline: expose a Stable Diffusion Space as an MCP tool. An orchestrator or agent can call the MCP endpoint with textual prompts and receive base64 images or URLs back, then pass those images to downstream vision models or UI components.
Audio transcription & search: register a Whisper-based Space. Upload recorded audio via the /tools/:id/invoke endpoint to get text transcripts. Store transcripts in a vector DB for semantic search, enabling voice-based retrieval and QA.
Text summarization and QA: wrap a text-generation or summarization Space as an MCP tool. Send long documents to the tool for summaries or question-answering. Because the server normalizes invocation, agents can switch models without changing orchestration code.
Desktop integration with Claude: enable Claude Desktop mode and host the MCP manifest on a reachable URL. Claude Desktop or other MCP-aware clients can discover your tools automatically, enabling a smooth workflow that mixes cloud and local models.

Tips for Developers

Use Docker Compose to manage credentials and persistent config. Place sensitive tokens in an .env file.
Start with a small subset of Spaces in config to validate routing, then add more tools incrementally.
If a Space requires multipart/form-data, adapt the client invocation to send files; the server proxies the request.
Monitor the /health and /tools endpoints for quick diagnostics; enable logging for request/response bodies during development.

For full implementation details and advanced configuration options, see the project repository on GitHub: https://github.com/evalstate/mcp-hfspace.

HuggingFace Spaces MCP Server: Image, Audio, Text Models