mcp-hfspace Serveur MCP 🤗

[!TIP]

Vous pouvez accéder et configurer les services MCP Hugging Face directement sur https://hf.co/mcp, y compris les espaces Gradio.

Ce projet a été remplacé par le serveur MCP officiel Hugging Face et les terminaux MCP Gradio.

Vous pouvez également exécuter hf-mcp-server localement en tant que serveur STDIO, ou avec un support robuste pour SSE, Streaming HTTP et Streaming HTTP JSON Mode. Cela permet également d'exécuter une interface utilisateur locale pour sélectionner les outils et les points de terminaison et de prendre en charge les notifications ToolListChangedNotifications.

hf.co/mcp

mcp-hfspace

Lisez l'introduction ici llmindset.co.uk/resources/mcp-hfspace/

Se connecter à Hugging Face Spaces avec un minimum d'installation - ajoutez simplement vos espaces et c'est parti !

Par défaut, il se connecte à black-forest-labs/FLUX.1-schnell fournissant des capacités de génération d'images à Claude Desktop.

Support MCP Gradio

[!TIP] Gradio 5.28 a maintenant un support MCP intégré via SSE : https://huggingface.co/blog/gradio-mcp. Vérifiez si votre espace cible est compatible avec MCP !

Installation

Le paquet NPM est @llmindset/mcp-hfspace.

Installez une version récente de NodeJS pour votre plateforme, puis ajoutez ce qui suit à la section mcpServers de votre fichier claude_desktop_config.json:

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

Assurez-vous que vous utilisez Claude Desktop 0.78 ou une version ultérieure.

Ceci vous permettra de démarrer avec un générateur d'images.

Configuration de base

Fournissez une liste d'espaces HuggingFace dans les arguments. mcp-hfspace trouvera le point de terminaison le plus approprié et le configurera automatiquement pour l'utilisation. Un exemple de claude_desktop_config.json est fourni ci-dessous.

Par défaut, le répertoire de travail actuel est utilisé pour le téléchargement de fichiers. Sous Windows, il s'agit d'un dossier en lecture/écriture à l'adresse \users\<username>\AppData\Roaming\Claude\<version .number\, et sous MacOS, il s'agit de la racine en lecture seule : /.

Il est recommandé de passer outre et de définir un répertoire de travail pour gérer le chargement et le téléchargement d'images et d'autres contenus sous forme de fichiers. Spécifiez l'argument --work-dir=/votre_répertoire ou la variable d'environnement MCP_HF_WORK_DIR.

Un exemple de configuration pour l'utilisation d'un générateur d'images moderne, d'un modèle de vision et de la synthèse vocale, avec un ensemble de répertoires de travail, est présenté ci-dessous :

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

Pour utiliser les espaces privés, fournissez votre Hugging Face Token avec l'argument --hf-token=hf_... ou la variable d'environnement HF_TOKEN.

Il est possible de lancer plusieurs instances du serveur pour utiliser des répertoires de travail et des jetons différents si nécessaire.

Traitement des fichiers et mode bureau Claude

Par défaut, le serveur fonctionne en mode bureau Claude. Dans ce mode, les images sont renvoyées dans les réponses de l'outil, tandis que les autres fichiers sont enregistrés dans le dossier de travail, leur chemin d'accès étant renvoyé sous forme de message. Ce mode donne généralement la meilleure expérience si l'on utilise Claude Desktop comme client.

Les URL peuvent également être fournies en tant qu'entrées : le contenu est transmis à l'outil Space.

Il y a une invite "Ressources disponibles" qui donne à Claude les fichiers et les types de mime disponibles dans votre répertoire de travail. C'est actuellement la meilleure façon de gérer les fichiers.

Exemple 1 - Génération d'images (Télécharger l'image / Vision de Claude)

Nous allons utiliser Claude pour comparer les images créées par shuttleai/shuttle-3.1-aesthetic et FLUX.1-schnell. Les images sont sauvegardées dans le répertoire de travail, et incluses dans la fenêtre contextuelle de Claude - afin que Claude puisse utiliser ses capacités de vision.

Exemple 2 - Modèle de vision (télécharger l'image)

Nous allons utiliser le lien spatialmerve/paligemma2-vqav2 pour interroger une image. Dans ce cas, nous spécifions le nom du fichier qui est disponible dans le répertoire de travail : nous ne voulons pas télécharger l'image directement dans la fenêtre contextuelle de Claude. Nous pouvons donc demander à Claude :

utiliser paligemma pour trouver qui est dans "test_gemma.jpg" -> Sortie texte : david bowie

Si vous téléchargez quelque chose dans le contexte de Claude, utilisez le bouton Paperclip Attachment, sinon indiquez le nom du fichier pour que le serveur l'envoie directement.

Nous pouvons également fournir une URL. Par exemple : utiliser paligemma pour détecter des humains dans https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> Une personne est détectée dans l'image - Taylor Swift sur scène.

Exemple 3 - Synthèse vocale (téléchargement audio)

En mode bureau de Claude, le fichier audio est enregistré dans le répertoire WORK_DIR, et Claude est informé de sa création. S'il n'est pas en mode bureau, le fichier est renvoyé au client sous la forme d'une ressource encodée en base64 (utile s'il prend en charge les pièces jointes audio intégrées).

Exemple 4 - Speech-to-Text (Upload Audio)

Ici, nous utilisons hf-audio/whisper-large-v3-turbo pour transcrire de l'audio et le mettre à la disposition de Claude.

Exemple 5 - Image-à-image

Dans cet exemple, nous spécifions le nom de fichier que microsoft/OmniParser doit utiliser, et nous obtenons en retour une image annotée et deux morceaux de texte distincts : les descriptions et les coordonnées. L'invite utilisée était " use omniparser to analyse ./screenshot.png and use the analysis to produce an artefact that reproducts that screen"(utiliser omniparser pour analyser ./screenshot.png et utiliser l'analyse pour produire un artefact reproduisant cet écran). DawnC/Pawmatch est également bon dans ce domaine.

Exemple 6 - Chat

Dans cet exemple, Claude propose un certain nombre d'énigmes de raisonnement à Qwen et pose des questions de suivi pour obtenir des éclaircissements.

Spécification du point de terminaison de l'API

Si vous le souhaitez, vous pouvez spécifier un point de terminaison d'API spécifique en l'ajoutant au nom d'espace. Ainsi, au lieu de passer Qwen/Qwen2.5-72B-Instruct, vous utiliserez Qwen/Qwen2.5-72B-Instruct/model_chat.

Mode bureau Claude

Ce mode peut être désactivé avec l'option --desktop-mode=false ou la variable d'environnement CLAUDE_DESKTOP_MODE=false. Dans ce cas, le contenu est renvoyé sous la forme d'une ressource intégrée encodée en Base64.

Espaces recommandés

Quelques espaces recommandés à essayer :

Génération d'images

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg (suppression de l'arrière-plan)
• diyism/Datou1111-shou_xin - Beaux dessins au crayon

Chat

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

Synthèse vocale / Génération audio

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

De la parole au texte

• hf-audio/whisper-large-v3-turbo
• (les modèles openai utilisent des paramètres non nommés et ne fonctionneront donc pas)

Du texte à la musique

• haoheliu/audioldm2-text2audio-text2music

Tâches de vision

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI
• DawnC/PawMatchAI/on_find_match_click - pour des recommandations interactives sur les chiens

Autres caractéristiques

Invitations

Des messages-guides sont générés pour chaque espace et permettent de saisir des informations. Gardez à l'esprit que souvent les espaces ne sont pas configurés avec des étiquettes particulièrement utiles, etc. Claude est en fait très doué pour cela, et la description de l'outil est très riche (mais non visible dans Claude Desktop).

Ressources

Une liste de fichiers dans le répertoire WORK_DIR est retournée, et par commodité, le nom est retourné sous forme de texte "Utiliser le fichier...". Si vous voulez ajouter quelque chose au contexte de Claude, utilisez le trombone - sinon spécifiez le nom du fichier pour le serveur MCP. Claude ne prend pas en charge la transmission de ressources à partir d'un contexte.

Espaces privés

Les espaces privés sont supportés par un jeton HuggingFace. Le jeton est utilisé pour télécharger et sauvegarder le contenu généré.

Utilisation de Claude Desktop

Pour utiliser Claude Desktop, ajoutez la configuration du serveur :

Sur MacOS : ~/Library/Application Support/Claude/claude_desktop_config.jsonSur 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" (... et ainsi de suite) ] } } }

Problèmes connus et limites

mcp-hfspace

• Les points de terminaison avec des paramètres non nommés ne sont pas pris en charge pour le moment.
• Traduction complète de certains types Python complexes vers des formats MCP adaptés.

Claude Desktop

• Claude Desktop 0.75 ne semble pas répondre aux erreurs du serveur MCP, et se termine à la place. Pour les problèmes persistants, utilisez l'inspecteur MCP pour mieux diagnostiquer ce qui ne va pas. Si quelque chose cesse soudainement de fonctionner, c'est probablement dû à l'épuisement de votre quota HuggingFace ZeroGPU - réessayez après une courte période, ou mettez en place votre propre espace d'hébergement.
• Claude Desktop semble utiliser un délai d'attente de 60s, et ne semble pas utiliser les notifications de progression pour gérer l'UX ou le keep-alive. Si vous utilisez des espaces ZeroGPU, les tâches lourdes ou volumineuses peuvent dépasser le délai d'attente. Vérifiez cependant le répertoire WORK_DIR pour les résultats ; le serveur MCP capturera et sauvegardera toujours le résultat s'il a été produit.
• Les rapports de Claude Desktops sur l'état du serveur, la journalisation, etc. ne sont pas excellents - utilisez @modelcontextprotocol/inspector pour aider à diagnostiquer les problèmes.

Espaces HuggingFace

• Si les quotas ou les files d'attente de ZeroGPU sont trop longs, essayez de dupliquer l'espace. Si votre travail prend moins de soixante secondes, vous pouvez généralement modifier le décorateur de fonction @spaces.GPU(duration=20) dans app.py pour demander moins de quota lors de l'exécution du travail.
• En passant HF_TOKEN, les quotas ZeroGPU s'appliqueront à votre compte (Pro) HF
• Si vous avez un espace privé, et du matériel dédié, votre HF_TOKEN vous donnera un accès direct à cet espace - aucun quota ne s'applique. Je vous le recommande si vous l'utilisez pour une quelconque tâche de production.

Services MCP tiers