mcp-hfspace

# mcp-hfspace MCP Server 🤗 > [!TIP] > > You can access and configure Hugging Face MCP services directly at https://hf.co/mcp, including Gradio spaces. > > 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). > > 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. ## hf.co/mcp  ## mcp-hfspace Read the introduction here [llmindset.co.uk/resources/mcp-hfspace/](https://llmindset.co.uk/resources/mcp-hfspace/) Connect to [Hugging Face Spaces](https://huggingface.co/spaces) with minimal setup needed - simply add your spaces and go! By default, it connects to `black-forest-labs/FLUX.1-schnell` providing Image Generation capabilities to Claude Desktop.  ## Gradio MCP Support > [!TIP] > 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! ## Installation 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: ```json "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: ```json "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. ## File Handling and Claude Desktop Mode 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. URLs can also be supplied as inputs: the content gets passed to the Space. 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. ### Example 1 - Image Generation (Download Image / Claude Vision) 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.  ### Example 2 - Vision Model (Upload Image) 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: `use paligemma to find out who is in "test_gemma.jpg"` -> `Text Output: david bowie`  _If you are uploading something to Claude's context use the Paperclip Attachment button, otherwise specify the filename for the Server to send directly._ 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 - T