Skip to content
Back to search

mcp-hfspace

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/evalstate--mcp-hfspace/badge.svg)](/listings/evalstate--mcp-hfspace)

HTML

<a href="/listings/evalstate--mcp-hfspace"><img src="/api/listings/evalstate--mcp-hfspace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

NPM Package is `@llmindset/mcp-hfspace`.

Install a recent version of [NodeJS](https://nodejs.org/en/download) 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. An example `claude_desktop_config.json` is supplied [below](#installation).

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 is the read-only root: `/`.

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

An example configuration for using a modern image generator, vision model and text to speech, with a working directory set is below:

    "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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 240 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-hfspace MCP Server 🤗
  2. > [!TIP]
  3. >
  4. > You can access and configure Hugging Face MCP services directly at https://hf.co/mcp, including Gradio spaces.
  5. >
  6. > This project has been superceded by the official [Hugging Face MCP Server](https://github.com/evalstate/hf-mcp-server) and [Gradio MCP Endpoints](https://huggingface.co/blog/gradio-mcp).
  7. >
  8. > Alternatively you can run hf-mcp-server locally as a STDIO Server, or with robust support for SSE, Streaming HTTP and Streaming HTTP JSON Mode. This also runs a local UI for selecting tools and endpoints and supports `ToolListChangedNotifications` too.
  9. ## hf.co/mcp
  10. ![image](https://github.com/user-attachments/assets/9cbf407b-2330-4330-8274-e47305a555b9)
  11. ## mcp-hfspace
  12. Read the introduction here [llmindset.co.uk/resources/mcp-hfspace/](https://llmindset.co.uk/resources/mcp-hfspace/)
  13. Connect to [Hugging Face Spaces](https://huggingface.co/spaces) with minimal setup needed - simply add your spaces and go!
  14. By default, it connects to `black-forest-labs/FLUX.1-schnell` providing Image Generation capabilities to Claude Desktop.
  15. ![Default Setup](./images/2024-12-09-flower.png)
  16. ## Gradio MCP Support
  17. > [!TIP]
  18. > Gradio 5.28 now has integrated MCP Support via SSE: https://huggingface.co/blog/gradio-mcp. Check out whether your target Space is MCP Enabled!
  19. ## Installation
  20. NPM Package is `@llmindset/mcp-hfspace`.
  21. Install a recent version of [NodeJS](https://nodejs.org/en/download) for your platform, then add the following to the `mcpServers` section of your `claude_desktop_config.json` file:
  22. ```json
  23. "mcp-hfspace": {
  24. "command": "npx",
  25. "args": [
  26. "-y",
  27. "@llmindset/mcp-hfspace"
  28. ]
  29. }
  30. ```
  31. Please make sure you are using Claude Desktop 0.78 or greater.
  32. This will get you started with an Image Generator.
  33. ### Basic setup
  34. Supply a list of HuggingFace spaces in the arguments. mcp-hfspace will find the most appropriate endpoint and automatically configure it for usage. An example `claude_desktop_config.json` is supplied [below](#installation).
  35. 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 is the read-only root: `/`.
  36. It is recommended to override this and set a Working Directory for handling the upload and download of images and other file-based content. Specify either the `--work-dir=/your_directory` argument or `MCP_HF_WORK_DIR` environment variable.
  37. An example configuration for using a modern image generator, vision model and text to speech, with a working directory set is below:
  38. ```json
  39. "mcp-hfspace": {
  40. "command": "npx",
  41. "args": [
  42. "-y",
  43. "@llmindset/mcp-hfspace",
  44. "--work-dir=/Users/evalstate/mcp-store",
  45. "shuttleai/shuttle-jaguar",
  46. "styletts2/styletts2",
  47. "Qwen/QVQ-72B-preview"
  48. ]
  49. }
  50. ```
  51. To use private spaces, supply your Hugging Face Token with either the `--hf-token=hf_...` argument or `HF_TOKEN` environment variable.
  52. It's possible to run multiple server instances to use different working directories and tokens if needed.
  53. ## File Handling and Claude Desktop Mode
  54. By default, the Server operates in _Claude Desktop Mode_. In this mode, Images are returned in the tool responses, while other files are saved in the working folder, their file path is returned as a message. This will usually give the best experience if using Claude Desktop as the client.
  55. URLs can also be supplied as inputs: the content gets passed to the Space.
  56. There is an "Available Resources" prompt that gives Claude the available files and mime types from your working directory. This is currently the best way to manage files.
  57. ### Example 1 - Image Generation (Download Image / Claude Vision)
  58. We'll use Claude to compare images created by `shuttleai/shuttle-3.1-aesthetic` and `FLUX.1-schnell`. The images gets saved to the Work Directory, as well as included in Claude's context window - so Claude can use its vision capabilities.
  59. ![Image Generation Comparison](./images/2024-12-05-flux-shuttle.png)
  60. ### Example 2 - Vision Model (Upload Image)
  61. We'll use `merve/paligemma2-vqav2` [space link](https://huggingface.co/spaces/merve/paligemma2-vqav2) to query an image. In this case, we specify the filename which is available in the Working Directory: we don't want to upload the Image directly to Claude's context window. So, we can prompt Claude:
  62. `use paligemma to find out who is in "test_gemma.jpg"` -> `Text Output: david bowie`
  63. ![Vision - File Upload](./images/2024-12-09-bowie.png)
  64. _If you are uploading something to Claude's context use the Paperclip Attachment button, otherwise specify the filename for the Server to send directly._
  65. We can also supply a URL. For example : `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.`
  66. ### Example 3 - Text-to-Speech (Download Audio)
  67. In _Claude Desktop Mode_, the audio file is saved in the WORK_DIR, and Claude is notified of the creation. If not in desktop mode, the file is returned as a base64 encoded resource to the Client (useful if it supports embedded Audio attachments).
  68. ![Voice Production](./images/2024-12-08-mcp-parler.png)
  69. ### Example 4 - Speech-to-Text (Upload Audio)
  70. Here, we use `hf-audio/whisper-large-v3-turbo` to transcribe some audio, and make it available to Claude.
  71. ![Audio Transcribe](./images/2024-12-09-transcribe.png)
  72. ### Example 5 - Image-to-Image
  73. In this example, we specify the filename for `microsoft/OmniParser` to use, and get returned an annotated Image and 2 separate pieces of text: descriptions and coordinates. The prompt used was `use omniparser to analyse ./screenshot.png` and `use the analysis to produce an artifact that reproduces that screen`. `DawnC/Pawmatch` is also good at this.
  74. ![Omniparser and Artifact](./images/2024-12-08-mcp-omni-artifact.png)
  75. ### Example 6 - Chat
  76. In this example, Claude sets a number of reasoning puzzles for Qwen, and asks follow-up questions for clarification.
  77. ![Qwen Reasoning Test](./images/2024-12-09-qwen-reason.png)
  78. ### Specifying API Endpoint
  79. If you need, you can specify a specific API Endpoint by adding it to the spacename. So rather than passing in `Qwen/Qwen2.5-72B-Instruct` you would use `Qwen/Qwen2.5-72B-Instruct/model_chat`.
  80. ### Claude Desktop Mode
  81. This can be disabled with the option --desktop-mode=false or the environment variable CLAUDE_DESKTOP_MODE=false. In this case, content as returned as an embedded Base64 encoded Resource.
  82. ## Recommended Spaces
  83. Some recommended spaces to try:
  84. ### Image Generation
  85. - shuttleai/shuttle-3.1-aesthetic
  86. - black-forest-labs/FLUX.1-schnell
  87. - yanze/PuLID-FLUX
  88. - gokaygokay/Inspyrenet-Rembg (Background Removal)
  89. - diyism/Datou1111-shou_xin - [Beautiful Pencil Drawings](https://x.com/ClementDelangue/status/1867318931502895358)
  90. ### Chat
  91. - Qwen/Qwen2.5-72B-Instruct
  92. - prithivMLmods/Mistral-7B-Instruct-v0.3
  93. ### Text-to-speech / Audio Generation
  94. - fantaxy/Sound-AI-SFX
  95. - parler-tts/parler_tts
  96. ### Speech-to-text
  97. - hf-audio/whisper-large-v3-turbo
  98. - (the openai models use unnamed parameters so will not work)
  99. ### Text-to-music
  100. - haoheliu/audioldm2-text2audio-text2music
  101. ### Vision Tasks
  102. - microsoft/OmniParser
  103. - merve/paligemma2-vqav2
  104. - merve/paligemma-doc
  105. - DawnC/PawMatchAI
  106. - DawnC/PawMatchAI/on_find_match_click - for interactive dog recommendations
  107. ## Other Features
  108. ### Prompts
  109. Prompts for each Space are generated, and provide an opportunity to input. Bear in mind that often Spaces aren't configured with particularly helpful labels etc. Claude is actually very good at figuring this out, and the Tool description is quite rich (but not visible in Claude Desktop).
  110. ### Resources
  111. A list of files in the WORK_DIR is returned, and as a convenience returns the name as "Use the file..." text. If you want to add something to Claude's context, use the paperclip - otherwise specify the filename for the MCP Server. Claude does not support transmitting resources from within Context.
  112. ### Private Spaces
  113. Private Spaces are supported with a HuggingFace token. The Token is used to download and save generated content.
  114. ### Using Claude Desktop
  115. To use with Claude Desktop, add the server config:
  116. On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  117. On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  118. ```json
  119. {
  120. "mcpServers": {
  121. "mcp-hfspace": {
  122. "command": "npx"
  123. "args": [
  124. "-y",
  125. "@llmindset/mcp-hfspace",
  126. "--work-dir=~/mcp-files/ or x:/temp/mcp-files/",
  127. "--HF_TOKEN=HF_{optional token}"
  128. "Qwen/Qwen2-72B-Instruct",
  129. "black-forest-labs/FLUX.1-schnell",
  130. "space/example/specific-endpint"
  131. (... and so on)
  132. ]
  133. }
  134. }
  135. }
  136. ```
  137. ## Known Issues and Limitations
  138. ### mcp-hfspace
  139. - Endpoints with unnamed parameters are unsupported for the moment.
  140. - Full translation from some complex Python types to suitable MCP formats.
  141. ### Claude Desktop
  142. - Claude Desktop 0.75 doesn't seem to respond to errors from the MCP Server, timing out instead. For persistent issues, use the MCP Inspector to get a better look at diagnosing what's going wrong. If something suddenly stops working, it's probably due to exhausting your HuggingFace ZeroGPU quota - try again after a short period, or set up your own Space for hosting.
  143. - Claude Desktop seems to use a hard timeout value of 60s, and doesn't appear to use Progress Notifications to manage UX or keep-alive. If you are using ZeroGPU spaces, large/heavy jobs may timeout. Check the WORK_DIR for results though; the MCP Server will still capture and save the result if it was produced.
  144. - Claude Desktops reporting of Server Status, logging etc. isn't great - use [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) to help diagnose issues.
  145. ### HuggingFace Spaces
  146. - If ZeroGPU quotas or queues are too long, try duplicating the space. If your job takes less than sixty seconds, you can usually change the function decorator `@spaces.GPU(duration=20)` in `app.py` to request less quota when running the job.
  147. - Passing HF_TOKEN will make ZeroGPU quotas apply to your (Pro) HF account
  148. - If you have a private space, and dedicated hardware your HF_TOKEN will give you direct access to that - no quota's apply. I recommend this if you are using for any kind of Production task.
  149. ## Third Party MCP Services
  150. <a href="https://glama.ai/mcp/servers/s57c80wvgq"><img width="380" height="200" src="https://glama.ai/mcp/servers/s57c80wvgq/badge" alt="mcp-hfspace MCP server" /></a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.