MCP Directory

How to add mcp-hfspace to Cursor

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

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the mcp-hfspace config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of mcp-hfspace's tools to confirm it's connected.

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 Cursor

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

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the mcp-hfspace config there under the "mcpServers" key and restart the client.

Is mcp-hfspace safe to use with Cursor?

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