MCP Directory

How to add mcp-hfspace to Claude Desktop

Connect Claude Desktop to any Hugging Face Space (Gradio app) with minimal setup — image gen, vision, TTS, STT and more. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 386★ · stdio · apikey

Claude Desktop config for mcp-hfspace

npx -y @llmindset/mcp-hfspace
{
  "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"
      ]
    }
  }
}

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the mcp-hfspace config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm mcp-hfspace's tools appear under the 🔌 tools menu.

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

What mcp-hfspace can do in Claude Desktop

(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'.

Security

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the mcp-hfspace config there under the "mcpServers" key and restart the client.

Is mcp-hfspace safe to use with Claude Desktop?

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.

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.

View repo Full mcp-hfspace page