mcp-hfspace MCP サーバー 🤗

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

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

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

インストール

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

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

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

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環境変数のいずれかを指定してください。

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

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

プライベートスペースを使用するには、 --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エンコードされたリソースとして返されます。

その他の機能

プロンプト

各スペースごとにプロンプトが生成され、入力の機会が提供されます。スペースには特に役立つラベルなどが設定されていないことが多いことにご注意ください。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

{
  "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)
        ]
    }
  }
}

既知の問題と制限事項

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)を変更することで、ジョブ実行時にクォータを少なく要求できます。
HuggingFace Pro アカウントをお持ちの場合は、Gradio API では ZeroGPU ジョブの追加見積もりは行われないことにご注意ください。これを実現するには、 X-IP-Tokenヘッダーを設定する必要があります。
プライベートスペースと専用ハードウェアをお持ちの場合は、HF_TOKEN を使用すると、クォータ制限なしで直接アクセスできます。本番環境のタスクに使用する場合は、HF_TOKEN の使用をお勧めします。

mcp-hfspace MCP Server

Integrations