📌Overview

Purpose: The mcp-hfspace framework is designed to facilitate seamless connections to Hugging Face Spaces for various AI tasks, including image generation, vision models, and audio processing with minimal setup.

Overview: The mcp-hfspace framework allows users to easily connect their applications to Hugging Face Spaces, enabling rich AI functionalities like image generation and text-to-speech. It supports both public and private spaces, enhances file handling, and optimizes the user experience within Claude Desktop.

Key Features:

• Ease of Setup: Minimal configuration is needed; simply add spaces to the framework via the claude_desktop_config.json file and it automatically configures the most suitable endpoints.

• Multi-functionality: Supports a variety of AI tasks including image generation, vision processing, text-to-speech, audio transcription, and image-to-image analysis, catering to diverse application needs.

• Claude Desktop Integration: Operates in Claude Desktop Mode, enhancing user experience by returning images directly in tool responses and effectively managing file paths.

• Private Space Access: Allows usage of private Hugging Face spaces with secure token support for added privacy and functionality.

• File Handling: Offers a streamlined approach to upload and download files, making it easy to manage resources and utilize them in AI tasks.

---

MCP-hfspace MCP Server 🤗

Connect to Hugging Face Spaces with minimal setup - just add your spaces and go! By default, it connects to evalstate/FLUX.1-schnell, providing Image Generation capabilities to Claude Desktop.

Installation

1. Install a recent version of NodeJS.

2. Add the following to the mcpServers section of your claude_desktop_config.json file:

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

Make sure you are using Claude Desktop 0.78 or greater.

Usage

• Supply a list of Hugging Face spaces in the arguments. The mcp-hfspace will find the most appropriate endpoint and configure it automatically.
• Override the default working directory for handling uploads/downloads by specifying --work-dir=/your_directory or using the MCP_HF_WORK_DIR environment variable.

Example configuration for using an image generator:

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

For private spaces, supply your Hugging Face Token using --hf-token=hf_... or HF_TOKEN environment variable. Multiple server instances can be run for different working directories and tokens.

File Handling and Claude Desktop Mode

By default, the server operates in Claude Desktop Mode. In this mode, images are returned in tool responses, while other files are saved in the working folder, and their paths returned as messages.

Examples

1. Image Generation: Compare images created by shuttleai/shuttle-3.1-aesthetic and FLUX.1-schnell.

2. Vision Model: Use merve/paligemma2-vqav2 to query an image without directly uploading it to Claude’s context.

3. Text-to-Speech: Audio files are saved in the WORK_DIR, and Claude is notified.

4. Speech-to-Text: Transcribe audio using hf-audio/whisper-large-v3-turbo.

5. Chat: Claude can set reasoning puzzles and ask follow-up questions.

Recommended Spaces

Image Generation

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell

Text-to-Speech

• fantaxy/Sound-AI-SFX

Speech-to-Text

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

Known Issues and Limitations

• Endpoints with unnamed parameters are currently unsupported.
• Timing out issues with Claude Desktop 0.75 may occur; use the MCP Inspector for troubleshooting.
• For Hugging Face Spaces, long queues or ZeroGPU quotas may require adjustments to the function decorator in your space's app.py.

---

For more detailed prompts and features, consult the documentation provided in this README.