MCP HubMCP Hub
evalstate

mcp-hfspace

by: evalstate

MCP Server to Use HuggingFace spaces, easy configuration and Claude Desktop mode.

219created 03/12/2024
Visit
HuggingFace
Claude

📌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 needed - simply add your spaces and go!

By default, it connects to black-forest-labs/FLUX.1-schnell providing Image Generation capabilities to Claude Desktop.

Installation

NPM Package is @llmindset/mcp-hfspsace.

Install a recent version of NodeJS for your platform, then add the following to the mcpServers section of your claude_desktop_config.json file:

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

Please make sure you are using Claude Desktop 0.78 or greater.

This will get you started with an Image Generator.

Basic setup

Supply a list of HuggingFace spaces in the arguments. mcp-hfspace will find the most appropriate endpoint and automatically configure it for usage.

By default, the current working directory is used for file upload/download. On Windows this is a read/write folder at \users\<username>\AppData\Roaming\Claude\<version.number>, and on MacOS it is the read-only root: /.

It is recommended to override this and set a Working Directory for handling upload and download of images and other file content. Specify either the --work-dir=/your_directory argument or MCP_HF_WORK_DIR environment variable.

Example configuration using multiple spaces and a working directory:

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

To use private spaces, supply your Hugging Face Token with either the --hf-token=hf_... argument or HF_TOKEN environment variable.

It's possible to run multiple server instances to use different working directories and tokens if needed.

File Handling and Claude Desktop Mode

By default, the Server operates in Claude Desktop Mode. In this mode:

  • Images are returned in the tool responses.
  • Other files are saved in the working folder, and their file path is returned as a message.

URLs can also be supplied as inputs; the content gets passed to the Space.

There is an "Available Resources" prompt that gives Claude the available files and mime types from your working directory, which helps manage files efficiently.

Examples

  • Image Generation (Download Image / Claude Vision)
    Claude can compare images created by multiple spaces. Images are saved to the working directory and included in Claude's context window for vision capabilities.

  • Vision Model (Upload Image)
    Use spaces like merve/paligemma2-vqav2 to query an image by specifying a filename or supplying a URL to detect objects or persons.

  • Text-to-Speech (Download Audio)
    Audio files are saved in the working directory; if not in desktop mode, files are returned as base64 encoded resources.

  • Speech-to-Text (Upload Audio)
    Use spaces like hf-audio/whisper-large-v3-turbo to transcribe audio and make text available to Claude.

  • Image-to-Image
    Specify filenames for spaces like microsoft/OmniParser to receive annotated images and associated text data.

  • Chat
    Support for multi-turn conversations and reasoning puzzles using chat-oriented spaces.

Specifying API Endpoint

You can specify a specific API Endpoint within a space by adding it to the space name, e.g., Qwen/Qwen2.5-72B-Instruct/model_chat.

Claude Desktop Mode

This mode can be disabled with --desktop-mode=false or setting the environment variable CLAUDE_DESKTOP_MODE=false, in which case content is returned as embedded Base64 encoded resources.

Recommended Spaces

Image Generation

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

Chat

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

Text-to-Speech / Audio Generation

  • 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
  • DawnC/PawMatchAI/on_find_match_click (for interactive dog recommendations)

Other Features

Prompts

Prompts for each Space are generated and provide input opportunities. Claude is effective at interpreting these prompts even if Spaces are not configured with helpful labels.

Resources

A list of files in the working directory is returned as "Use the file..." text. To add content to Claude’s context, use the paperclip attachment button; otherwise specify the filename for the MCP Server.

Private Spaces

Private Spaces are supported with a HuggingFace token used to download and save generated content.

Using Claude Desktop

To integrate with Claude Desktop, add the server config in the appropriate file:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

Example snippet:

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=~/mcp-files/ or x:/temp/mcp-files/",
        "--HF_TOKEN=HF_{optional token}",
        "Qwen/Qwen2-72B-Instruct",
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpoint"
      ]
    }
  }
}

Known Issues and Limitations

mcp-hfspace

  • Endpoints with unnamed parameters are currently unsupported.
  • Some complex Python types may not fully translate to suitable MCP formats.

Claude Desktop

  • Claude Desktop 0.75 may timeout on server errors rather than report them.
  • Uses a 60s hard timeout and no progress notifications, leading to potential timeouts with heavy jobs.
  • Server status and logging are limited; use @modelcontextprotocol/inspector for diagnosis.

HuggingFace Spaces

  • ZeroGPU quotas and queues can cause delays or failures; duplicating spaces or adjusting GPU quotas in app.py can help.
  • Passing HF_TOKEN applies ZeroGPU quotas to your account.
  • For private spaces with dedicated hardware, the token provides direct access without quotas, recommended for production use.