mcp-hfspace
Connect Claude Desktop to any Hugging Face Space (Gradio app) with minimal setup — image gen, vision, TTS, STT and more.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @llmindset/mcp-hfspacePaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"mcp-hfspace": {
"command": "npx",
"args": [
"-y",
"@llmindset/mcp-hfspace",
"--work-dir=/Users/evalstate/mcp-store",
"shuttleai/shuttle-jaguar",
"styletts2/styletts2",
"Qwen/QVQ-72B-preview"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Node.js (a recent version)
- Claude Desktop 0.78 or greater (for use with Claude Desktop)
- A Hugging Face token (optional — only for private Spaces or to apply your own ZeroGPU quota)
- A configured working directory (recommended) via --work-dir or MCP_HF_WORK_DIR
About mcp-hfspace
mcp-hfspace exposes Hugging Face Spaces (Gradio apps) as MCP tools so Claude Desktop and other MCP clients can call them. You list one or more Spaces in the config; the server picks the most appropriate API endpoint for each and wires it up automatically. It handles file uploads/downloads through a working directory, accepts URL inputs, supports private Spaces via an HF token, and offers a Claude Desktop Mode that returns images inline while saving other files to disk. Each configured Space becomes a callable tool, and prompts plus an 'Available Resources' helper expose the files in your working directory.
Tools & capabilities (1)
(per-Space tool)Each Hugging Face Space listed in the configuration is exposed as its own tool. The server automatically selects the most appropriate Gradio API endpoint for the Space (e.g. image generation for FLUX.1-schnell, transcription for whisper-large-v3-turbo, vision Q&A for paligemma2-vqav2). A specific endpoint can be forced by appending it to the space name, e.g. 'Qwen/Qwen2.5-72B-Instruct/model_chat'.
When to use it
- Generate images in Claude Desktop using Spaces like FLUX.1-schnell or shuttleai/shuttle-3.1-aesthetic, with results saved to disk and shown to Claude's vision
- Query or analyze images with vision Spaces (e.g. merve/paligemma2-vqav2, microsoft/OmniParser) by referencing a local file or URL
- Produce speech/audio from text via text-to-speech Spaces (e.g. parler-tts/parler_tts, styletts2/styletts2)
- Transcribe audio to text with speech-to-text Spaces (e.g. hf-audio/whisper-large-v3-turbo)
- Generate music from text with text-to-music Spaces (e.g. haoheliu/audioldm2-text2audio-text2music)
- Chat with hosted LLM Spaces (e.g. Qwen/Qwen2.5-72B-Instruct) from within Claude
Security notes
Optional. A Hugging Face token (--hf-token=hf_... or HF_TOKEN env var) is only needed for private Spaces or to apply your own (Pro) ZeroGPU quota. Passing HF_TOKEN routes ZeroGPU usage to your HF account; with a private Space on dedicated hardware no quotas apply. By default the current working directory is used for file upload/download — on macOS this defaults to the read-only root '/', so it is strongly recommended to set --work-dir or MCP_HF_WORK_DIR to a dedicated read/write folder.
mcp-hfspace FAQ
Do I need a Hugging Face token?
No, not for public Spaces. A token (--hf-token=hf_... or the HF_TOKEN environment variable) is only required for private Spaces, or if you want ZeroGPU quota to apply to your own (Pro) HF account or to access dedicated private hardware.
Why should I set a working directory?
The working directory handles file upload and download for images, audio and other content. By default the current working directory is used — on macOS this is the read-only root '/' and on Windows a folder under AppData/Roaming. It is recommended to override this with --work-dir=/your_directory or the MCP_HF_WORK_DIR environment variable.
What is Claude Desktop Mode?
It is the default mode. Images are returned inline in tool responses (so Claude can use its vision), while other files are saved to the working directory and their path is reported back. It can be disabled with --desktop-mode=false or CLAUDE_DESKTOP_MODE=false, in which case content is returned as base64-encoded embedded resources.
Are there any limitations?
Yes. Endpoints with unnamed parameters are not currently supported (so some Spaces, e.g. certain OpenAI Whisper Spaces, will not work), and full translation of some complex Python types to MCP formats is incomplete. Also, Claude Desktop uses a hard ~60s timeout, so heavy ZeroGPU jobs may time out — though the server still saves results to the working directory if produced.
Is this the official Hugging Face MCP server?
No. This is a community project by evalstate. Per its README it has been superseded by the official Hugging Face MCP Server and Gradio's native MCP endpoints (available at hf.co/mcp), but the package remains installable.
Alternatives to mcp-hfspace
Compare all alternatives →
Official MCP server providing persistent, file-backed knowledge-graph memory across sessions.
Structured step-by-step reasoning tool for breaking problems into revisable thought sequences.
Fully managed remote server for AWS docs, blogs, What's-New and Well-Architected guidance — no key.
Compare mcp-hfspace with: