HuggingFace Spaces

Servidor para usar HuggingFace Spaces, compatible con imágenes, audio, texto y más. Modo Claude Desktop para facilidad de uso.

GitHub

388

Prueba este MCPPatrocinado

Documentación

Servidor MCP mcp-hfspace 🤗

[!TIP]

Puedes acceder y configurar los servicios MCP de Hugging Face directamente en https://hf.co/mcp,, incluidos los espacios de Gradio.

Este proyecto ha sido superado por el Servidor MCP de Hugging Face oficial y los Endpoints MCP de Gradio.

Alternativamente, puedes ejecutar hf-mcp-server localmente como un servidor STDIO, o con soporte robusto para SSE, HTTP de transmisión y modo JSON de HTTP de transmisión. Esto también ejecuta una interfaz de usuario local para seleccionar herramientas y endpoints, y también admite ToolListChangedNotifications.

hf.co/mcp

mcp-hfspace

Lee la introducción aquí llmindset.co.uk/resources/mcp-hfspace/

Conéctate a Hugging Face Spaces con una configuración mínima: ¡simplemente agrega tus espacios y listo!

Por defecto, se conecta a black-forest-labs/FLUX.1-schnell proporcionando capacidades de generación de imágenes a Claude Desktop.

Default Setup

Soporte MCP de Gradio

[!TIP] Gradio 5.28 ahora tiene soporte MCP integrado a través de SSE: https://huggingface.co/blog/gradio-mcp. ¡Comprueba si tu Space objetivo está habilitado para MCP!

Instalación

El paquete NPM es @llmindset/mcp-hfspace.

Instala una versión reciente de NodeJS para tu plataforma y luego agrega lo siguiente a la sección mcpServers de tu archivo claude_desktop_config.json:

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

Asegúrate de estar usando Claude Desktop 0.78 o superior.

Esto te permitirá comenzar con un generador de imágenes.

Configuración básica

Proporciona una lista de espacios de HuggingFace en los argumentos. mcp-hfspace encontrará el endpoint más adecuado y lo configurará automáticamente para su uso. Se proporciona un ejemplo de claude_desktop_config.json a continuación.

Por defecto, se utiliza el directorio de trabajo actual para la carga/descarga de archivos. En Windows, esta es una carpeta de lectura/escritura en \users\<username>\AppData\Roaming\Claude\<version.number\, y en MacOS es la raíz de solo lectura: /.

Se recomienda anular esto y establecer un directorio de trabajo para manejar la carga y descarga de imágenes y otro contenido basado en archivos. Especifica el argumento --work-dir=/your_directory o la variable de entorno MCP_HF_WORK_DIR.

A continuación se muestra un ejemplo de configuración para usar un generador de imágenes moderno, un modelo de visión y texto a voz, con un directorio de trabajo establecido:

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/evalstate/mcp-store",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ]
    }

Para usar espacios privados, proporciona tu token de Hugging Face con el argumento --hf-token=hf_... o la variable de entorno HF_TOKEN.

Es posible ejecutar múltiples instancias del servidor para usar diferentes directorios de trabajo y tokens si es necesario.

Manejo de archivos y modo Claude Desktop

Por defecto, el servidor opera en modo Claude Desktop. En este modo, las imágenes se devuelven en las respuestas de la herramienta, mientras que otros archivos se guardan en la carpeta de trabajo y su ruta de archivo se devuelve como mensaje. Esto suele dar la mejor experiencia si usas Claude Desktop como cliente.

También se pueden proporcionar URLs como entradas: el contenido se pasa al Space.

Hay un prompt de "Recursos disponibles" que le da a Claude los archivos disponibles y los tipos MIME de tu directorio de trabajo. Esta es actualmente la mejor manera de gestionar archivos.

Ejemplo 1 - Generación de imágenes (descargar imagen / visión de Claude)

Usaremos Claude para comparar imágenes creadas por shuttleai/shuttle-3.1-aesthetic y FLUX.1-schnell. Las imágenes se guardan en el directorio de trabajo y también se incluyen en la ventana de contexto de Claude, para que Claude pueda usar sus capacidades de visión.

Image Generation Comparison

Ejemplo 2 - Modelo de visión (subir imagen)

Usaremos merve/paligemma2-vqav2 enlace del space para consultar una imagen. En este caso, especificamos el nombre de archivo que está disponible en el directorio de trabajo: no queremos subir la imagen directamente a la ventana de contexto de Claude. Entonces, podemos pedirle a Claude:

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

Si estás subiendo algo al contexto de Claude, usa el botón de adjuntar clip, de lo contrario especifica el nombre de archivo para que el servidor lo envíe directamente.

También podemos proporcionar una URL. Por ejemplo: 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.

Ejemplo 3 - Texto a voz (descargar audio)

En modo Claude Desktop, el archivo de audio se guarda en WORK_DIR y se notifica a Claude de su creación. Si no está en modo escritorio, el archivo se devuelve como un recurso codificado en base64 al cliente (útil si admite archivos adjuntos de audio incrustados).

Voice Production

Ejemplo 4 - Voz a texto (subir audio)

Aquí, usamos hf-audio/whisper-large-v3-turbo para transcribir algo de audio y ponerlo a disposición de Claude.

Audio Transcribe

Ejemplo 5 - Imagen a imagen

En este ejemplo, especificamos el nombre de archivo para que microsoft/OmniParser lo use, y obtenemos una imagen anotada y 2 piezas de texto separadas: descripciones y coordenadas. El prompt utilizado fue use omniparser to analyse ./screenshot.png y use the analysis to produce an artifact that reproduces that screen. DawnC/Pawmatch también es bueno en esto.

Omniparser and Artifact

Ejemplo 6 - Chat

En este ejemplo, Claude plantea una serie de acertijos de razonamiento para Qwen y hace preguntas de seguimiento para aclarar.

Qwen Reasoning Test

Especificar endpoint de API

Si lo necesitas, puedes especificar un endpoint de API concreto añadiéndolo al nombre del space. Así, en lugar de pasar Qwen/Qwen2.5-72B-Instruct, usarías Qwen/Qwen2.5-72B-Instruct/model_chat.

Modo Claude Desktop

Esto se puede deshabilitar con la opción --desktop-mode=false o la variable de entorno CLAUDE_DESKTOP_MODE=false. En este caso, el contenido se devuelve como un recurso incrustado codificado en Base64.

Spaces recomendados

Algunos spaces recomendados para probar:

Generación de imágenes

shuttleai/shuttle-3.1-aesthetic
black-forest-labs/FLUX.1-schnell
yanze/PuLID-FLUX
gokaygokay/Inspyrenet-Rembg (Eliminación de fondo)
diyism/Datou1111-shou_xin - Hermosos dibujos a lápiz

Chat

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

Texto a voz / Generación de audio

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

Voz a texto

hf-audio/whisper-large-v3-turbo
(los modelos de openai usan parámetros sin nombre, por lo que no funcionarán)

Texto a música

haoheliu/audioldm2-text2audio-text2music

Tareas de visión

microsoft/OmniParser
merve/paligemma2-vqav2
merve/paligemma-doc
DawnC/PawMatchAI
DawnC/PawMatchAI/on_find_match_click - para recomendaciones interactivas de perros

Otras características

Prompts

Se generan prompts para cada Space y brindan una oportunidad de entrada. Ten en cuenta que a menudo los Spaces no están configurados con etiquetas particularmente útiles, etc. Claude es en realidad muy bueno para resolver esto, y la descripción de la herramienta es bastante rica (pero no visible en Claude Desktop).

Recursos

Se devuelve una lista de archivos en WORK_DIR y, como conveniencia, devuelve el nombre como texto "Usa el archivo...". Si quieres agregar algo al contexto de Claude, usa el clip; de lo contrario, especifica el nombre de archivo para el servidor MCP. Claude no admite transmitir recursos desde el contexto.

Spaces privados

Los Spaces privados son compatibles con un token de HuggingFace. El token se usa para descargar y guardar el contenido generado.

Usar Claude Desktop

Para usar con Claude Desktop, agrega la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En 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)
        ]
    }
  }
}

Problemas y limitaciones conocidos

mcp-hfspace

Los endpoints con parámetros sin nombre no son compatibles por el momento.
Traducción completa de algunos tipos complejos de Python a formatos MCP adecuados.

Claude Desktop

Claude Desktop 0.75 no parece responder a los errores del servidor MCP, sino que se agota el tiempo de espera. Para problemas persistentes, usa el Inspector MCP para obtener una mejor visión del diagnóstico de lo que está fallando. Si algo deja de funcionar repentinamente, probablemente se deba a que agotaste tu cuota de ZeroGPU de HuggingFace: inténtalo de nuevo después de un breve período o configura tu propio Space para alojamiento.
Claude Desktop parece usar un valor de tiempo de espera fijo de 60 segundos y no parece usar notificaciones de progreso para gestionar la experiencia de usuario o mantener la conexión. Si usas spaces de ZeroGPU, los trabajos grandes/pesados pueden agotar el tiempo de espera. Sin embargo, revisa WORK_DIR para ver los resultados; el servidor MCP aún capturará y guardará el resultado si se produjo.
El informe de estado del servidor, registro, etc. de Claude Desktop no es muy bueno: usa @modelcontextprotocol/inspector para ayudar a diagnosticar problemas.