HuggingFace Spaces Connector MCP server

This Node.js package connects your Claude Desktop client to Hugging Face Spaces through the Model Context Protocol (MCP), enabling AI capabilities like image generation, vision models, and text-to-speech with minimal setup.

Installation

To get started with mcp-hfspace, you'll need to:

1. Install a recent version of NodeJS for your platform
2. Add the following configuration to the mcpServers section of your Claude Desktop config file:

"mcp-hfspace": {
  "command": "npx",
  "args": [
    "-y",
    "@llmindset/mcp-hfspace"
  ]
}

The config file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Make sure you're using Claude Desktop 0.78 or greater.

Basic Configuration

You can specify Hugging Face spaces as arguments to connect to different AI capabilities. The server will automatically configure the appropriate endpoints.

Setting a Working Directory

It's recommended to set a working directory for handling file uploads and downloads:

"mcp-hfspace": {
  "command": "npx",
  "args": [
    "-y",
    "@llmindset/mcp-hfspace",
    "--work-dir=/path/to/your/directory",
    "shuttleai/shuttle-jaguar",
    "styletts2/styletts2",
    "Qwen/QVQ-72B-preview"
  ]
}

You can set the working directory using either:

• The --work-dir=/your_directory argument
• The MCP_HF_WORK_DIR environment variable

Using Private Spaces

To access private Hugging Face spaces, provide your token using either:

• The --hf-token=hf_... argument
• The HF_TOKEN environment variable

Usage Examples

Image Generation

Use spaces like shuttleai/shuttle-3.1-aesthetic or black-forest-labs/FLUX.1-schnell for generating images. Simply ask Claude to generate an image with your chosen model, and the image will be saved to your working directory and included in Claude's context window.

Vision Models

For analyzing images, you can use spaces like merve/paligemma2-vqav2:

1. Place an image in your working directory
2. Ask Claude to analyze it: use paligemma to find out who is in "image.jpg"

You can also provide image URLs: use paligemma to detect humans in https://example.com/image.jpg

Text-to-Speech

With spaces like parler-tts/parler_tts, you can generate audio:

1. Ask Claude to create speech with your chosen model
2. The audio file will be saved to your working directory

Speech-to-Text

Use transcription models like hf-audio/whisper-large-v3-turbo:

1. Place an audio file in your working directory
2. Ask Claude to transcribe it using the model

Image-to-Image Processing

For image analysis and transformation, try spaces like microsoft/OmniParser or gokaygokay/Inspyrenet-Rembg (for background removal):

1. Place an image in your working directory
2. Ask Claude to analyze or transform it using your chosen model

Chat with Other AI Models

You can connect to other AI chat models like Qwen/Qwen2.5-72B-Instruct to have Claude interact with them.

Advanced Configuration

Specifying API Endpoints

You can specify a particular API endpoint by adding it to the space name:

Qwen/Qwen2.5-72B-Instruct/model_chat

Disabling Claude Desktop Mode

By default, the server operates in Claude Desktop Mode. You can disable this using:

• The --desktop-mode=false argument
• The CLAUDE_DESKTOP_MODE=false environment variable

Recommended Spaces

Image Generation

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg (Background Removal)
• diyism/Datou1111-shou_xin (Pencil Drawings)

Chat

• Qwen/Qwen2.5-72B-Instruct
• prithivMLmods/Mistral-7B-Instruct-v0.3

Text-to-Speech

• fantaxy/Sound-AI-SFX
• parler-tts/parler_tts

Speech-to-Text

• hf-audio/whisper-large-v3-turbo

Text-to-Music

• haoheliu/audioldm2-text2audio-text2music

Vision Tasks

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI

Troubleshooting

• If a space suddenly stops working, you may have exhausted your Hugging Face ZeroGPU quota. Try again after a short period.
• Claude Desktop has a hard timeout of 60 seconds. Large jobs may time out, but check your working directory as the server may still save the result.
• For better diagnostics, use @modelcontextprotocol/inspector.
• If ZeroGPU quotas are limiting you, try duplicating the space or modifying the @spaces.GPU(duration=20) decorator in the space's app.py to request less quota.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.