mcp-hfspace

mcp-hfspace MCP サーバー 🤗

紹介文はこちらをご覧くださいllmindset.co.uk/resources/mcp-hfspace/

最小限の設定でHugging Face Spacesに接続できます。スペースを追加するだけですぐに使用できます。

デフォルトでは、 black-forest-labs/FLUX.1-schnellに接続し、Claude Desktop にイメージ生成機能を提供します。

Gradio MCP サポート

[!TIP] Gradio 5.28 では、SSE 経由で MCP サポートが統合されました: https://huggingface.co/blog/gradio-mcp 。対象のスペースで MCP が有効になっているかどうかを確認してください。

インストール

NPM パッケージは@llmindset/mcp-hfspaceです。

お使いのプラットフォーム用の最新バージョンのNodeJSをインストールし、 claude_desktop_config.jsonファイルのmcpServersセクションに次のコードを追加します。

Claude Desktop 0.78 以上を使用していることを確認してください。

これにより、画像ジェネレーターの使用を開始できます。

基本設定

引数にHuggingFaceスペースのリストを指定してください。mcp-hfspaceは最適なエンドポイントを見つけ、自動的に設定して使用できます。claude_desktop_config.json claude_desktop_config.json例を以下に示します。

デフォルトでは、ファイルのアップロード/ダウンロードには現在の作業ディレクトリが使用されます。Windowsでは、これは\users\<username>\AppData\Roaming\Claude\<version.number\にある読み取り/書き込み可能なフォルダです。MacOSでは、読み取り専用のルートディレクトリである/です。

画像やその他のファイルベースのコンテンツのアップロードとダウンロードを処理するための作業ディレクトリを設定することをお勧めします。-- --work-dir=/your_directory引数またはMCP_HF_WORK_DIR環境変数のいずれかを指定してください。

作業ディレクトリが設定された、最新の画像ジェネレーター、ビジョン モデル、およびテキスト読み上げ機能を使用するための構成例を以下に示します。

プライベート スペースを使用するには、 --hf-token=hf_...引数またはHF_TOKEN環境変数のいずれかを使用して Hugging Face トークンを指定します。

必要に応じて、複数のサーバー インスタンスを実行して、異なる作業ディレクトリとトークンを使用することもできます。

ファイル処理とClaudeデスクトップモード

デフォルトでは、サーバーはClaude Desktopモードで動作します。このモードでは、画像はツールのレスポンスで返され、その他のファイルは作業フォルダに保存され、ファイルパスはメッセージとして返されます。Claude Desktopをクライアントとして使用する場合、通常はこのモードが最適なエクスペリエンスを提供します。

URL を入力として提供することもできます。その場合、コンテンツがスペースに渡されます。

「利用可能なリソース」プロンプトがあり、作業ディレクトリにある利用可能なファイルとMIMEタイプをClaudeに表示します。これは現在、ファイル管理に最適な方法です。

例1 - 画像生成（画像のダウンロード / Claude Vision）

Claudeを使ってshuttleai/shuttle-3.1-aestheticとFLUX.1-schnellで作成された画像を比較します。画像は作業ディレクトリに保存され、Claudeのコンテキストウィンドウにも表示されるため、Claudeは視覚機能を利用できます。

例2 - ビジョンモデル（画像のアップロード）

merve/paligemma2-vqav2スペースリンクを使って画像をクエリします。今回は、作業ディレクトリにあるファイル名を指定します。Claude のコンテキストウィンドウに画像を直接アップロードしたくないためです。そこで、Claude に次のように指示します。

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

Claude のコンテキストに何かをアップロードする場合は、Paperclip Attachment ボタンを使用します。それ以外の場合は、サーバーが直接送信するファイル名を指定します。

URLを指定することもできます。例えば、 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.

例3 - テキスト読み上げ（音声のダウンロード）

Claudeデスクトップモードでは、オーディオファイルはWORK_DIRに保存され、Claudeに作成が通知されます。デスクトップモードでない場合は、ファイルはbase64エンコードされたリソースとしてクライアントに返されます（埋め込みオーディオ添付ファイルをサポートしている場合に便利です）。

例4 - 音声テキスト変換（音声のアップロード）

ここでは、 hf-audio/whisper-large-v3-turboを使用して音声を書き起こし、Claude が利用できるようにします。

例5 - 画像から画像へ

この例では、 microsoft/OmniParserで使用するファイル名を指定し、注釈付きの画像と、説明と座標という2つのテキストを返します。プロンプトはuse omniparser to analyse ./screenshot.png 、 use the analysis to produce an artifact that reproduces that screen 。DawnC DawnC/Pawmatchも同様に優れています。

例6 - チャット

この例では、クロードはクウェンにいくつかの推論パズルを設定し、説明のために追加の質問をします。

APIエンドポイントの指定

必要であれば、スペース名にAPIエンドポイントを追加することで、特定のAPIエンドポイントを指定できます。つまりQwen/Qwen2.5-72B-Instructを渡す代わりに、 Qwen/Qwen2.5-72B-Instruct/model_chatを使用します。

クロードデスクトップモード

これは、オプション --desktop-mode=false または環境変数 CLAUDE_DESKTOP_MODE=false で無効にできます。この場合、コンテンツは埋め込まれたBase64エンコードされたリソースとして返されます。

おすすめスペース

試してみるのにおすすめのスペース:

画像生成

• シャトルアイ/シャトル-3.1-美学
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg（背景除去）
• diyism/Datou1111-shou_xin -美しい鉛筆画

チャット

• Qwen/Qwen2.5-72B-インストラクト
• prithivMLmods/Mistral-7B-Instruct-v0.3

テキスト読み上げ/オーディオ生成

• ファンタクシー/サウンドAISFX
• parler-tts/parler_tts

音声テキスト変換

• HFオーディオ/ウィスパーラージV3ターボ
• （OpenAIモデルは名前のないパラメータを使用するため動作しません）

テキストから音楽へ

• haoheliu/audioldm2-text2audio-text2music

ビジョンタスク

• マイクロソフト/オムニパーサー
• merve/paligemma2-vqav2
• merve/paligemma-doc
• ドーンC/パウマッチAI
• DawnC/PawMatchAI/on_find_match_click - インタラクティブな犬の推奨

その他の機能

プロンプト

各スペースごとにプロンプトが生成され、入力の機会が提供されます。スペースには特に役立つラベルなどが設定されていないことが多いことにご注意ください。Claudeはこの点を非常にうまく理解しており、ツールの説明も非常に充実しています（ただし、Claude Desktopでは表示されません）。

リソース

WORK_DIR内のファイルのリストが返されます。便宜上、ファイル名は「Use the file...」というテキストで返されます。Claudeのコンテキストに何かを追加する場合は、ペーパークリップを使用してください。それ以外の場合は、MCPサーバーのファイル名を指定してください。Claudeは、コンテキスト内からのリソースの転送をサポートしていません。

プライベートスペース

プライベートスペースはHuggingFaceトークンでサポートされます。このトークンは、生成されたコンテンツをダウンロードして保存するために使用されます。

Claudeデスクトップの使用

Claude Desktop で使用するには、サーバー設定を追加します。

MacOS の場合: ~/Library/Application Support/Claude/claude_desktop_config.json Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

既知の問題と制限事項

mcp-hfspace

• 名前のないパラメータを持つエンドポイントは現時点ではサポートされていません。
• いくつかの複雑な Python 型から適切な MCP 形式への完全な変換。

クロードデスクトップ

• Claude Desktop 0.75 は MCP サーバーからのエラーに応答せず、タイムアウトしてしまうようです。問題が解決しない場合は、MCP Inspector を使用して、問題の原因をより詳しく診断してください。突然動作しなくなった場合は、HuggingFace ZeroGPU のクォータを使い果たした可能性があります。しばらくしてからもう一度お試しください。または、ホスティング用の独自のスペースを設定してください。
• Claude Desktop は60秒のハードタイムアウト値を使用しているようで、UX やキープアライブの管理に Progress Notifications は使用していないようです。ZeroGPU スペースを使用している場合、大規模または高負荷のジョブはタイムアウトする可能性があります。ただし、WORK_DIR で結果を確認してください。MCP サーバーは、生成された結果を取得して保存します。
• Claude Desktops のサーバー ステータスやログなどのレポートはあまり優れていません。問題の診断には@modelcontextprotocol/inspectorを使用してください。

ハギングフェイススペース

• ZeroGPUのクォータやキューが長すぎる場合は、スペースを複製してみてください。ジョブの実行時間が60秒未満であれば、通常はapp.pyの関数デコレータ@spaces.GPU(duration=20)を変更することで、ジョブ実行時にクォータを少なく要求できます。
• HF_TOKENを渡すと、ZeroGPUクォータが（Pro）HFアカウントに適用されます。
• プライベートスペースと専用ハードウェアをお持ちの場合は、HF_TOKEN を使用すると、クォータ制限なしで直接アクセスできます。本番環境のタスクに使用する場合は、HF_TOKEN の使用をお勧めします。

サードパーティのMCPサービス