Servidor MCP mcp-hfspace 🤗

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

Conéctese a Hugging Face Spaces con una configuración mínima: ¡simplemente agregue sus espacios y listo!

De forma predeterminada, se conecta a evalstate/FLUX.1-schnell y proporciona capacidades de generación de imágenes a Claude Desktop.

Instalación

El paquete NPM es @llmindset/mcp-hfspsace .

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

Asegúrese de estar utilizando Claude Desktop 0.78 o superior.

Esto le permitirá comenzar a utilizar 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 adecuado y lo configurará automáticamente para su uso. A continuación se proporciona un ejemplo claude_desktop_config.json .

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

Se recomienda anular esto y configurar un directorio de trabajo para gestionar la carga y descarga de imágenes y otro contenido basado en archivos. Especifique 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 utilizar un generador de imágenes moderno, un modelo de visión y texto a voz con un directorio de trabajo configurado como se muestra a continuación:

Para utilizar espacios privados, proporcione a su token Hugging Face el argumento --hf-token=hf_... o la variable de entorno HF_TOKEN .

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

Manejo de archivos y modo de escritorio Claude

De forma predeterminada, 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 y su ruta se devuelve como un mensaje. Esto suele ofrecer la mejor experiencia si se utiliza Claude Desktop como cliente.

Las URL también se pueden proporcionar como entradas: el contenido se pasa al espacio.

Hay un mensaje de "Recursos disponibles" que le indica a Claude los archivos y tipos MIME disponibles en su directorio de trabajo. Actualmente, esta es la mejor manera de administrar archivos.

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

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 se incluyen en la ventana contextual de Claude, para que este pueda usar sus funciones de visión.

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

Usaremos el enlace espacial merve/paligemma2-vqav2 para consultar una imagen. En este caso, especificamos el nombre del archivo disponible en el directorio de trabajo: no queremos subir la imagen directamente a la ventana contextual de Claude. Por lo tanto, podemos indicarle a Claude:

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

Si está cargando algo en el contexto de Claude, utilice el botón Adjunto de clip; de lo contrario, especifique el nombre del 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 el modo de escritorio de Claude , el archivo de audio se guarda en WORK_DIR y se notifica a Claude sobre su creación. Si no está en modo de escritorio, el archivo se devuelve al cliente como un recurso codificado en base64 (útil si admite archivos adjuntos de audio incrustados).

Ejemplo 4: Conversión de 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.

Ejemplo 5 - Imagen a imagen

En este ejemplo, especificamos el nombre de archivo que usará microsoft/OmniParser y obtenemos una imagen anotada y dos fragmentos de texto separados: descripciones y coordenadas. El mensaje 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 eficaz en esto.

Ejemplo 6 - Chat

En este ejemplo, Claude propone una serie de acertijos de razonamiento para Qwen y formula preguntas de seguimiento para aclararlos.

Especificación del punto final de la API

Si lo necesita, puede especificar un punto final de API específico añadiéndolo al nombre del espacio. Por lo tanto, en lugar de pasar Qwen/Qwen2.5-72B-Instruct debería usar Qwen/Qwen2.5-72B-Instruct/model_chat .

Modo de escritorio de Claude

Esto se puede desactivar 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
• laboratorios de la selva negra/FLUX.1-schnell
• yanze/PuLID-FLUX
• Inspyrenet-Rembg (Eliminación de fondo)
• diyism/Datou1111-shou_xin - Hermosos dibujos a lápiz

Charlar

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

Generación de texto a voz / audio

• fantasía/Sonido-AI-SFX
• parler-tts/parler_tts

Conversión de voz a texto

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

Texto a música

• haoheliu/audioldm2-texto2audio-texto2música

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

Indicaciones

Se generan indicaciones para cada espacio que permiten introducir información. Tenga en cuenta que, a menudo, los espacios no se configuran con etiquetas útiles. Claude es muy hábil para resolver este problema, y la descripción de la herramienta es bastante completa (aunque no está visible en Claude Desktop).

Recursos

Se devuelve una lista de archivos en WORK_DIR y, para mayor comodidad, el nombre se devuelve como texto "Usar el archivo...". Si desea agregar algo al contexto de Claude, utilice el clip; de lo contrario, especifique el nombre del archivo para el servidor MCP. Claude no admite la transmisión de recursos desde el contexto.

Espacios privados

Los espacios privados se respaldan con un token HuggingFace. Este token se utiliza para descargar y guardar el contenido generado.

Uso de Claude Desktop

Para utilizar con Claude Desktop, agregue la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

Problemas y limitaciones conocidos

espacio mcp-hf

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

Escritorio de Claude

• Claude Desktop 0.75 no parece responder a los errores del servidor MCP, sino que se agota el tiempo de espera. Si persisten los problemas, use el Inspector de MCP para diagnosticar mejor el problema. Si algo deja de funcionar repentinamente, probablemente se deba a que se agotó su cuota de HuggingFace ZeroGPU. Inténtelo de nuevo después de un rato o configure su propio espacio de alojamiento.
• Claude Desktop parece usar un tiempo de espera fijo de 60 s y no parece usar notificaciones de progreso para gestionar la experiencia de usuario ni el mantenimiento de la actividad. Si utiliza espacios con cero GPU, es posible que se agote el tiempo de espera de los trabajos grandes o pesados. Sin embargo, revise WORK_DIR para ver los resultados; el servidor MCP capturará y guardará el resultado si se generó.
• Los informes de Claude Desktops sobre el estado del servidor, el registro, etc. no son muy buenos: use @modelcontextprotocol/inspector para ayudar a diagnosticar problemas.

Espacios para abrazarse

• Si las cuotas o colas de ZeroGPU son demasiado largas, intente duplicar el espacio. Si su trabajo tarda menos de sesenta segundos, generalmente puede cambiar el decorador de funciones @spaces.GPU(duration=20) en app.py para solicitar menos cuota al ejecutar el trabajo.
• Si tiene una cuenta HuggingFace Pro, tenga en cuenta que la API de Gradio no le ofrece una cotización adicional para trabajos ZeroGPU: deberá configurar un encabezado X-IP-Token para lograrlo.
• Si tienes un espacio privado y hardware dedicado, tu HF_TOKEN te dará acceso directo a él, sin cuotas. Lo recomiendo si lo usas para cualquier tarea de producción.

Servicios MCP de terceros