mcp-hfspace Servidor MCP 🤗

[CONSEJO]

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

Este proyecto ha sido sustituido por el servidor MCP oficial de Hugging Face y Gradio MCP Endpoints.

Alternativamente, puedes ejecutar hf-mcp-server localmente como un servidor STDIO, o con soporte robusto para SSE, Streaming HTTP y Streaming HTTP JSON Mode. Esto también ejecuta una interfaz de usuario local para seleccionar herramientas y puntos finales y también soporta ToolListChangedNotifications.

hf.co/mcp

mcp-hfspace

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

Conéctate a Hugging Face Spaces con una configuración mínima - ¡simplemente añade 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.

Soporte MCP de Gradio

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

Instalación

El paquete NPM es @llmindset/mcp-hfspace.

Instale una versión reciente de NodeJS para su plataforma, luego añada lo siguiente a la sección mcpServers de su archivo claude_desktop_config.json:

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

Asegúrese de que está utilizando Claude Desktop 0.78 o superior.

Esto le permitirá empezar con un generador de imágenes.

Configuración básica

Proporcione una lista de espacios HuggingFace en los argumentos. mcp-hfspace encontrará el punto final más apropiado y lo configurará automáticamente para su uso. A continuación se proporciona un ejemplo claude_desktop_config.json.

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

Se recomienda anular esto y establecer un directorio de trabajo para gestionar la carga y descarga de imágenes y otros contenidos basados en archivos. Especifique el argumento --work-dir=/su_directorio o la variable de entorno MCP_HF_WORK_DIR.

A continuación se muestra un ejemplo de configuración para utilizar 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 utilizar espacios privados, proporcione su token de Hugging Face con el argumento --hf-token=hf_... o con la variable de entorno HF_TOKEN.

Es posible ejecutar varias instancias del servidor para utilizar diferentes directorios de trabajo y tokens si es necesario.

Manejo de archivos y modo de escritorio Claude

Por defecto, el servidor funciona 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, su ruta de archivo se devuelve como un mensaje. Esto suele dar la mejor experiencia si se utiliza Claude Desktop como cliente.

Las URL también se pueden suministrar como entradas: el contenido se pasa al Espacio.

Hay un indicador de "Recursos disponibles" que proporciona a Claude los archivos y tipos mime disponibles en su directorio de trabajo. Esta es actualmente la mejor forma de gestionar archivos.

Ejemplo 1 - Generación de imágenes (Descargar imagen / Claude Vision)

Utilizaremos Claude para comparar imágenes creadas por shuttleai/shuttle-3.1-aesthetic y FLUX.1-schnell. Las imágenes se guardarán en el directorio de trabajo y se incluirán en la ventana contextual de Claude, para que Claude pueda utilizar sus capacidades de visión.

Ejemplo 2 - Modelo de Visión (Cargar Imagen)

Usaremos el enlace espacialmerve/paligemma2-vqav2 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 contextual de Claude. Por lo tanto, podemos pedirle a Claude

use paligemma para averiguar quién está en "prueba_gemma.jpg" -> Salida de texto: david bowie

Si está subiendo algo al contexto de Claude utilice el botón Paperclip Attachment, de lo contrario especifique el nombre del archivo para que el Servidor lo envíe directamente.

También podemos suministrar una URL. Por ejemplo: use paligemma para detectar humanos en https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> Se detecta una persona en la imagen - Taylor Swift en el escenario.

Ejemplo 3 - Texto a voz (Descargar audio)

En el modo escritorio de Claude, el archivo de audio se guarda en el WORK_DIR, y Claude es notificado de la 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).

Ejemplo 4 - Voz a texto (cargar audio)

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

Ejemplo 5 - Imagen a imagen

En este ejemplo, especificamos el nombre de archivo para que microsoft/OmniParser lo utilice, y se nos devuelve una Imagen anotada y 2 piezas separadas de texto: descripciones y coordenadas. La instrucción utilizada fue utilizar omniparser para analizar ./screenshot.png y utilizar el análisis para producir un artefacto que reproduzca esa pantalla. DawnC/Pawmatch también sirve para esto.

Ejemplo 6 - Chat

En este ejemplo, Claude establece una serie de rompecabezas de razonamiento para Qwen, y hace preguntas de seguimiento para su aclaración.

Especificación del punto final de la API

Si lo necesitas, puedes especificar un API Endpoint específico añadiéndolo al spacename. Así, en lugar de pasar Qwen/Qwen2.5-72B-Instruct utilizarías Qwen/Qwen2.5-72B-Instruct/model_chat.

Claude Modo Escritorio

Puede desactivarse 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.

Espacios recomendados

Algunos espacios recomendados para probar:

Generación de imágenes

• shuttleai/shuttle-3.1-estética
• 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

De voz a texto

• hf-audio/whisper-large-v3-turbo
• (los modelos openai utilizan 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 sobre perros

Otras funciones

Avisos

Se generan avisos para cada espacio y ofrecen la oportunidad de introducir datos. Tenga en cuenta que a menudo los espacios no están configurados con etiquetas especialmente útiles, etc. Claude es muy bueno en 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 el WORK_DIR, y como conveniencia devuelve el nombre como texto "Use el archivo...". Si desea añadir algo al contexto de Claude, utilice el clip; de lo contrario, especifique el nombre del archivo para el Servidor MCP. Claude no soporta la transmisión de recursos desde dentro del contexto.

Espacios privados

Los Espacios Privados se soportan con un token HuggingFace. El Token se utiliza para descargar y guardar contenido generado.

Uso de Claude Desktop

Para utilizar con Claude Desktop, añada la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonEn 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" (... y así sucesivamente) ] } }

Problemas conocidos y limitaciones

mcp-hfspace

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

Claude Desktop

• Claude Desktop 0.75 no parece responder a los errores del servidor MCP, sino que se desconecta. Para problemas persistentes, utilice el Inspector MCP para diagnosticar mejor lo que está fallando. Si algo deja de funcionar de repente, probablemente se deba a que se ha agotado tu cuota de HuggingFace ZeroGPU - inténtalo de nuevo tras un breve periodo de tiempo, o configura tu propio Espacio para el alojamiento.
• Claude Desktop parece utilizar un valor de tiempo de espera duro de 60s, y no parece utilizar notificaciones de progreso para gestionar UX o keep-alive. Si estás usando espacios ZeroGPU, los trabajos grandes/pesados pueden perder el tiempo de espera. Sin embargo, compruebe el WORK_DIR para ver los resultados; el Servidor MCP capturará y guardará el resultado si se ha producido.
• Los informes de Claude Desktops sobre el estado del servidor, el registro, etc. no son muy buenos. Utilice @modelcontextprotocol/inspector para ayudar a diagnosticar problemas.

Espacios HuggingFace

• Si las cuotas o colas de ZeroGPU son demasiado largas, intenta duplicar el espacio. Si tu trabajo tarda menos de sesenta segundos, normalmente puedes cambiar el decorador de función @spaces.GPU(duration=20) en app.py para solicitar menos cuota al ejecutar el trabajo.
• Pasar HF_TOKEN hará que las cuotas ZeroGPU se apliquen a tu cuenta (Pro) HF
• Si tienes un espacio privado, y hardware dedicado tu HF_TOKEN te dará acceso directo a eso - no se aplican cuotas. Yo recomiendo esto si usted está utilizando para cualquier tipo de tarea de producción.

Servicios MCP de terceros