MCP Hfspace

What evalstate/mcp-hfspace MCP server does

The evalstate/mcp-hfspace MCP server exposes Hugging Face Spaces to an MCP client, with Claude Desktop as the documented client. It is intended for tasks such as image generation, chat, vision analysis, text-to-speech, speech-to-text, image-to-image processing, and other Space-supported operations.

The server can be started with one or more Space names. It finds an appropriate endpoint and creates tools for interacting with those Spaces. A specific endpoint can also be selected by appending its endpoint path to the Space name.

How it works

The server provides a semantic Space search tool, a resource listing tool, and endpoint-specific tools. search-spaces finds possible Hugging Face Spaces from a short task description and returns the matches in a table. available-files reports files in the configured working directory, including names, sizes, modification times, MIME types, and resource URIs.

Configured Spaces receive inputs from the MCP client. Inputs may include local filenames or URLs. Depending on the client mode and file type, generated content is either included in the response or written to the working directory. In Claude Desktop Mode, images are returned in tool responses, while other files are saved locally and their paths are reported.

Setup and configuration

Install Node.js and add the npm package @llmindset/mcp-hfspace to the mcpServers section of Claude Desktop’s configuration. The documented command uses npx -y, followed by the package name and any Space names. Claude Desktop 0.78 or newer is required according to the setup instructions.

Set a working directory with --work-dir=/path or the MCP_HF_WORK_DIR environment variable. This directory is used for uploaded and downloaded files. The default depends on the current working directory and the operating system, so specifying one is recommended for predictable file handling.

Private Spaces require a Hugging Face token supplied through --hf-token or HF_TOKEN. The evalstate/mcp-hfspace MCP server can run multiple instances when separate working directories or tokens are needed. Claude Desktop Mode can be disabled with --desktop-mode=false or CLAUDE_DESKTOP_MODE=false, causing files to be returned as embedded Base64 resources instead.

Tools and capabilities

The listed tools include:

• available-files for identifying local resources such as recent images or audio files.
• search-spaces for finding Hugging Face Space endpoints by task description.
• FLUX_1-schnell-infer for calling the default FLUX.1-schnell inference endpoint.

Configured Spaces can support image, audio, and text uploads and downloads. The README documents examples involving image generation, image uploads for vision models, audio generation, transcription, chat, and image-to-image processing. Actual inputs and outputs depend on the selected Space and endpoint.

Limitations and notes

The repository README states that this project has been superseded by Hugging Face’s official MCP Server and Gradio MCP Endpoints. It also points to hf.co/mcp as a way to access and configure Hugging Face MCP services directly.

Space metadata and input labels may not always be clear, although the server generates prompts and tool descriptions from each Space. The available resources mechanism is intended to help the client identify files in the working directory. Claude Desktop does not support transmitting resources from within context, so specifying a filename is recommended when a file should be uploaded directly to a Space.