HuggingFace Spaces

HuggingFace Spaces

Server for using HuggingFace Spaces with image, audio, text models; includes Claude Desktop mode.

369
Stars
57
Forks
8
Releases

Overview

mcp-hfspace is an MCP server that connects Claude Desktop (and other MCP clients) to Hugging Face Spaces. It provides a NodeJS package (@llmindset/mcp-hfspace) that you configure in claude_desktop_config.json's mcpServers section; it runs via npx and can handle multiple working directories and HF tokens. By default, it connects to black-forest-labs/FLUX.1-schnell to provide Image Generation capabilities to Claude Desktop. The server can auto-detect and configure endpoints for the spaces you supply, supports private spaces using a Hugging Face token, and allows multiple instances with separate work directories and tokens. Claude Desktop mode can embed images in tool responses while other generated content is saved to the working directory and referenced by file paths. You can supply URLs or file names to Spaces, and a local working directory stores uploads/downloads for reuse. API endpoints can be customized by using a subpath on the spacename (e.g., model_chat). Gradio MCP support via SSE is noted for Gradio 5.28. The README also notes that this project has been superseded by the official Hugging Face MCP Server and Gradio MCP Endpoints.

Details

Owner
evalstate
Language
TypeScript
License
MIT License
Updated
2025-12-07

Features

Gradio MCP Support (SSE)

Gradio 5.28 adds integrated MCP support via SSE, enabling MCP endpoints for Spaces.

Default HuggingFace Spaces integration

Automatically connects to a default image-generation Space (black-forest-labs/FLUX.1-schnell) and exposes it via MCP to Claude Desktop.

Working directory management

Configurable work directory for file uploads/downloads; override with --work-dir or MCP_HF_WORK_DIR.

HF Token and Private Spaces

Supports private Spaces using a HuggingFace token via --hf-token or HF_TOKEN env var.

Multiple server instances

Supports running multiple server instances with different working directories and tokens.

Claude Desktop mode behavior

In Claude Desktop mode, images are returned in tool responses and other files saved to the working directory with their paths returned.

API Endpoint customization

You can specify specific API endpoints by using a sub-path on the spacename, e.g., model_chat.

Audience

Claude Desktop usersConfigure and run Hugging Face Spaces MCP endpoints within Claude Desktop.
MCP DevelopersSet up MCP endpoints and configurations for multiple spaces in Claude Desktop.
HuggingFace Space AdminsManage private spaces and tokens for production MCP usage at scale.

Tags

Hugging Face SpacesMCPClaude DesktopGradio MCPImage GenerationVisionText-to-SpeechSpeech-to-TextPrivate SpacesSSEStreaming HTTPHF TokenWork DirectoryEndpoints