MCP Directory

How to add mcp-hfspace to Windsurf

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

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the mcp-hfspace config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5mcp-hfspace's tools become available to Cascade.

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 Windsurf

(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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the mcp-hfspace config there under the "mcpServers" key and restart the client.

Is mcp-hfspace safe to use with Windsurf?

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