mcp-hfspace Command-Line Utility Server 🤗

Consult the introductory documentation here llmindset.co.uk/resources/mcp-hfspace/

Establish connectivity to Hugging Face Spaces requiring negligible prerequisite adjustments—just input your desired spaces and commence operation!

By default, this utility connects to the evalstate/FLUX.1-schnell deployment, offering robust Image Generation capabilities to the Claude Desktop environment.

Deployment Procedure

The requisite NPM package is @llmindset/mcp-hfspsace.

Install a current version of NodeJS compatible with your operating system, subsequently augmenting the mcpServers segment within your claude_desktop_config.json file as follows:

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

Ensure that you are operating with Claude Desktop version 0.78 or a later release.

This configuration initializes the system with an integrated Image Generator.

Fundamental Configuration

Provide an enumeration of HuggingFace Spaces within the execution arguments. The mcp-hfspace tool will dynamically ascertain the most suitable endpoint and automatically establish the necessary configuration for utilization. An illustrative claude_desktop_config.json example is referenced subsequently.

The current execution directory serves as the default repository for file staging (uploads/downloads). On Windows platforms, this typically resolves to a read/write location at \users\<username>\AppData\Roaming\Claude\<version.number>, whereas on macOS, it defaults to the read-only root directory: /.

It is strongly advised to supersede this default by designating an explicit Working Directory for the management of image and other file-based data transfers. Define this either via the --work-dir=/your_directory argument or by setting the MCP_HF_WORK_DIR environmental variable.

Below is an example configuration demonstrating the use of a contemporary image synthesis model, a vision analysis model, and text-to-speech functionality, complete with a specified 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 interface with proprietary (private) Spaces, furnish your Hugging Face authentication token using either the --hf-token=hf_... argument or the HF_TOKEN environment variable.

It is feasible to instantiate several server instances concurrently, each configured with distinct working directories and authentication credentials, should the need arise.

Data Handling and Claude Desktop Operational Mode

By default, the server operates in Claude Desktop Mode. Under this regime, generated images are directly embedded within the tool responses, whereas other file types are persisted to the designated working folder, with their corresponding file paths conveyed in a message. This behavior generally yields the optimal user experience when employing Claude Desktop as the client interface.

Uniform Resource Locators (URLs) may also be supplied as input data; the content referenced by the URL is subsequently transmitted to the associated Space.

An "Available Resources" notification is periodically presented, enumerating the files and associated MIME types resident in your working directory. Presently, this mechanism represents the superior method for file lifecycle management.

Scenario 1 - Image Synthesis (Image Retrieval / Claude Vision Integration)

We will employ Claude to conduct a comparative analysis between visuals generated by shuttleai/shuttle-3.1-aesthetic and FLUX.1-schnell. The resultant images are persisted to the Work Directory and simultaneously injected into Claude's context window, enabling leveraged use of its visual comprehension faculties.

Scenario 2 - Vision Model Query (Image Upload for Inspection)

We utilize the merve/paligemma2-vqav2 space link to pose queries against an image asset. In this specific instance, we cite the filename, which is accessible within the Working Directory; our objective is to bypass direct image upload into Claude's contextual memory. Thus, a suitable prompt for Claude would be:

use paligemma to find out who is in "test_gemma.jpg" -> Text Output: david bowie

If transferring content into Claude's context, utilize the Paperclip Attachment mechanism; otherwise, explicitly state the filename for direct relay by the Server.

We can equivalently submit a remote URL. For instance: use paligemma to detect humans in https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> One person is detected in the image - Taylor Swift on stage.

Scenario 3 - Text-to-Speech Synthesis (Audio File Download)

Within Claude Desktop Mode, the synthesized audio asset is written to the WORK_DIR, and Claude is notified of its creation. If not operating in desktop mode, the asset is transmitted as a base64 encoded resource back to the Client (beneficial if the client supports inline Audio attachments).

Scenario 4 - Speech-to-Text Transcription (Audio File Upload)

Here, we employ hf-audio/whisper-large-v3-turbo to process an audio input and render the resulting text available for consumption by Claude.

Scenario 5 - Image-to-Image Transformation

In this operational example, we supply the necessary filename argument for microsoft/OmniParser to process, receiving back a visually annotated image along with two discrete text outputs: descriptive metadata and spatial coordinates. The preceding user instruction was use omniparser to analyse ./screenshot.png followed by use the analysis to produce an artifact that reproduces that screen. The model DawnC/Pawmatch excels at comparable tasks.

Scenario 6 - Conversational AI Interaction

This example illustrates Claude formulating a sequence of logical challenges for the Qwen model and subsequently requesting subsequent conversational turns for necessary clarification.

Specifying the API Entrypoint

If required, you can designate a particular API endpoint by appending it directly to the space identifier. For instance, instead of supplying Qwen/Qwen2.5-72B-Instruct, you would specify Qwen/Qwen2.5-72B-Instruct/model_chat.

Deactivating Claude Desktop Mode

This default behavior can be suppressed via the --desktop-mode=false argument or by setting the environment variable CLAUDE_DESKTOP_MODE=false. In the deactivated state, all content is transmitted as an embedded Base64 encoded Resource.

Suggested Deployments

Certain spaces are recommended for initial exploration:

Image Generation

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• Inspyrenet-Rembg (For background abstraction)
• diyism/Datou1111-shou_xin - Stunning Pencil Sketch Emulation

Conversational Models

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

Text-to-Speech / Audio Synthesis

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

Speech-to-Text Transcription

• hf-audio/whisper-large-v3-turbo
• (Note: OpenAI models utilize unlabelled parameters and are thus incompatible)

Text-to-Music Generation

• haoheliu/audioldm2-text2audio-text2music

Visual Analysis Tasks

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI
• DawnC/PawMatchAI/on_find_match_click - For interactive canine matching recommendations

Supplementary Features

Input Prompts

Parameter prompts are algorithmically generated for each Space, offering an avenue for user input configuration. Keep in mind that the underlying Spaces are not always provisioned with intuitive labels. Claude's inherent aptitude for inference allows it to deduce functionality effectively, and the Tool's description is quite detailed (though not immediately visible in Claude Desktop).

Resource Manifest

A roster of files located in the WORK_DIR is returned, conveniently mapping the filename to the accessible text phrase "Use the file...". If you intend to introduce an asset into Claude's working context, employ the paperclip mechanism; otherwise, specify the file's name for the MCP Server to handle. Claude does not currently support resource transference originating from within the Context area.

Proprietary Spaces Access

Support for private Spaces is established via the provision of a HuggingFace authentication token. This token is utilized for securely downloading and persisting generated assets.

Integration with Claude Desktop

To enable functionality with Claude Desktop, incorporate the server configuration into the appropriate location:

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

{ "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-endpint" (... and so on) ] } } }

Recognized Impediments and Constraints

mcp-hfspace Specifics

• Function deployments featuring unnamed input parameters are presently unsupported.
• Complete transformation of certain intricate Python data structures into compliant MCP formats remains a challenge.

Claude Desktop Context

• Claude Desktop build 0.75 appears unresponsive to error signals originating from the MCP Server, leading instead to operation timeouts. For recurring failures, leverage the MCP Inspector tool for more granular diagnostic review. If functionality abruptly ceases, the likely cause is the exhaustion of your HuggingFace ZeroGPU allotment; please attempt the operation again after a brief interval, or establish your own dedicated hosting Space.
• Claude Desktop seems to enforce a fixed operational time limit of 60 seconds and lacks visible Progress Notifications for user experience feedback or connection maintenance (keep-alive). If utilizing ZeroGPU spaces, computationally intensive jobs risk timing out. Nevertheless, verify the contents of the WORK_DIR for successful outputs; the MCP Server will generally capture and store the result if it was successfully generated.
• The reporting capabilities within Claude Desktop concerning Server Status, logging, etc., are suboptimal—utilize the @modelcontextprotocol/inspector utility for troubleshooting assistance.

HuggingFace Spaces Considerations

• Should ZeroGPU quotas be depleted or queues become excessively long, attempt creating a duplicate of the Space. If your job execution time is below sixty seconds, modifying the function decorator from @spaces.GPU(duration=20) in app.py to request a lower quota might resolve the issue when running the task.
• If you possess a HuggingFace Pro subscription, be aware that the Gradio API does not automatically inherit your supplementary quota for ZeroGPU operations—you must explicitly include an X-IP-Token header to secure this benefit.
• For private Spaces hosted on dedicated hardware, your HF_TOKEN grants direct access, bypassing standard quota restrictions. This level of access is highly recommended for any mission-critical or production workloads.

Ancillary MCP Services

ENCYCLOPEDIA ENTRY: XMLHttpRequest (XHR) defines an Application Programming Interface, manifested as a JavaScript object, whose methods facilitate the transmission of HTTP requests from a web browser environment to a designated web server. These methods empower browser-resident applications to dispatch inquiries to the server subsequent to page rendering completion, and subsequently retrieve data in response. XMLHttpRequest is a foundational element of the Ajax programming paradigm. Preceding Ajax, the fundamental mechanisms for server interaction relied primarily on hyperlink navigation and form submissions, often resulting in the complete replacement of the currently viewed page content.

== Historical Context == The conceptual foundation for XMLHttpRequest was formulated in the year 2000 by the development team responsible for Microsoft Outlook. This concept was subsequently realized within the Internet Explorer 5 browser release (1999). However, the initial invocation syntax did not employ the XMLHttpRequest identifier. Instead, the developers relied upon the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Since the release of Internet Explorer 7 (2006), ubiquity in support for the XMLHttpRequest identifier has been achieved across all major browser platforms. The XMLHttpRequest identifier is now universally recognized as the standard across all leading web browsers, encompassing Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published a Working Draft specification detailing the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C advanced this to the Level 2 Working Draft specification. Level 2 introduced augmented capabilities, notably methods for tracking event progression, enabling cross-origin requests, and managing binary data streams. By the close of 2011, the Level 2 specification was successfully integrated back into the primary specification document. At the conclusion of 2012, stewardship of further development transitioned to the WHATWG, which now maintains a continuously evolving document utilizing Web IDL definitions.

== Operational Usage == Generally, executing a request via XMLHttpRequest necessitates adherence to several programmatic stages.

1. Instantiate an XMLHttpRequest object by invoking its constructor:
2. Invoke the "open" method to delineate the request methodology, pinpoint the target resource URI, and select either synchronous or asynchronous processing mode:
3. For asynchronous operations, establish a callback listener function that will be alerted upon changes in the request's status:
4. Commence the transmission of the request by calling the "send" method:
5. Handle status changes within the designated event listener. If the server returns payload data, this is, by default, captured within the "responseText" attribute. When the object completes its processing cycle, its status transitions to state 4, the terminal "done" state. Beyond these fundamental procedures, XMLHttpRequest offers numerous options to govern request transmission parameters and response handling logic. Custom header fields can be appended to the request to instruct the server on fulfillment criteria, and data can be uploaded to the server via an argument passed to the "send" invocation. The received payload can be deserialized from JSON format into an immediately usable JavaScript structure, or processed iteratively as data segments arrive, obviating the need to await the entirety of the text response. The operation can be terminated prematurely or configured to fail if completion is not achieved within a stipulated temporal window.

== Requests Across Domain Boundaries ==

In the nascent phases of the World Wide Web's evolution, it was observed to be feasible to breach