mcp-hfspace

You can run Hugging Face MCP spaces locally as an MCP Server to connect Claude Desktop with a variety of Space endpoints. This setup lets you generate images, use vision capabilities, and access text-to-speech or speech-to-text features through a single MCP server workflow.

How to use

Configure your MCP client to connect to a local stdio MCP server built around Hugging Face MCP spaces. You’ll run the server via npm/npx and point it at the spaces you want to use. The server handles work directories, token-based private spaces, and different endpoints, presenting results back to your client in a streamlined flow.

How to install

Prerequisites you need before starting:

• Node.js: install a recent LTS version for your platform.

• npm or npx: comes with Node.js; you will use npx to run the MCP server package.

Configuration and usage examples

{
  "mcpServers": {
    "mcp_hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/yourname/mcp-store",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ],
      "env": [
        {"name": "HF_TOKEN", "value": "YOUR_TOKEN"}
      ]
    }
  }
}

Notes about working directory and private spaces

By default, images and other generated content are stored in a Working Directory you specify. Set the working directory with the --work-dir option or the MCP_HF_WORK_DIR environment variable to direct where uploads and downloads are saved.

Using private spaces and tokens

To access private Hugging Face spaces, provide a Hugging Face token either via --hf-token on the command line or by setting the HF_TOKEN environment variable. This enables private space usage and content access.

Available tools and capabilities

The MCP server exposes a range of capabilities derived from Hugging Face Spaces: image generation, vision/model inputs, text-to-speech, speech-to-text, and image-to-image workflows. It also supports multiple spaces, private spaces with tokens, and a working directory for file-based content. Tools are exposed as endpoints you can invoke through your MCP client, enabling a cohesive workflow across generation, analysis, and refinement.

Troubleshooting and limitations

If you encounter issues, check that the Working Directory is accessible and that the HF_TOKEN (if using private spaces) is valid. For long-running jobs, be mindful of potential timeouts in client environments and ensure the MCP server has completed its tasks before proceeding. If a job appears stuck, verify the space endpoints and the configured spaces list.

Summary of requirements for Claude Desktop integration

To use with Claude Desktop, ensure your claude_desktop_config.json includes the mcp-hfspace stdio server with the correct command and arguments. The example configuration shows how to start the server and pass the target spaces to it.

Configuration references

Example usage is provided in the following JSON snippet which you can adapt to your environment. Replace the work directory path and spaces with your own choices.