mcp-hfspace MCP Server 🤗

mcp-hfspace MCP サーバー 🤗

ヒント

Gradio スペースを含む Hugging Face MCP サービスには、https://hf.co/mcp から直接アクセスして設定できます。

このプロジェクトは、公式の Hugging Face MCP Server と Gradio MCP Endpoints に引き継がれました。

または、hf-mcp-server を STDIO サーバーとしてローカルで実行することも、SSE、Streaming HTTP、Streaming HTTP JSON Mode をしっかりサポートした形で実行することもできます。ツールとエンドポイントを選択するためのローカル UI も起動し、ToolListChangedNotifications にも対応しています。

hf.co/mcp

mcp-hfspace

こちらの紹介記事をご覧ください：llmindset.co.uk/resources/mcp-hfspace/

最小限のセットアップで Hugging Face Spaces に接続できます。Spaces を追加するだけで利用できます。

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

Gradio の MCP サポート

ヒント

Gradio 5.28 では、SSE による MCP サポートが統合されました：https://huggingface.co/blog/gradio-mcp。対象の Space が MCP に対応しているかどうかをご確認ください。

インストール

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

お使いのプラットフォーム用の最新バージョンの NodeJS をインストールしてから、claude_desktop_config.json ファイルの mcpServers セクションに以下を追加してください。

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

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

これで画像生成を始められます。

基本的なセットアップ

引数に HuggingFace Spaces のリストを指定してください。mcp-hfspace が最適なエンドポイントを見つけ、使用できるように自動で設定します。設定例の 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"
      ]
    }

プライベート Space を使用するには、--hf-token=hf_... 引数または HF_TOKEN 環境変数で Hugging Face Token を指定してください。

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

ファイルの処理と Claude Desktop モード

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

入力として URL を指定することもできます。コンテンツは Space に渡されます。

「Available Resources」プロンプトでは、作業ディレクトリ内の利用可能なファイルと 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" -> テキスト出力: david bowie

Claudeのコンテキストに何かをアップロードする場合は、クリップの添付ボタンを使ってください。それ以外の場合は、サーバーから直接送信するファイル名を指定してください。

URLを指定することもできます。例：use paligemma to detect humans in https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> 画像内に1人検出されました - ステージ上のTaylor Swiftです。

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

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

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

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

例 5 - 画像から画像への変換

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

例 6 - チャット

この例では、ClaudeがQwenにいくつかの推論パズルを出題し、明確化のための追加質問をしています。

APIエンドポイントの指定

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

Claude Desktop Mode

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

おすすめのSpaces

試してみるのにおすすめのスペースをいくつか紹介します。

画像生成

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg（背景の削除）
• diyism/Datou1111-shou_xin - 美しい鉛筆画

チャット

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

テキスト読み上げ／音声生成

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

音声テキスト変換

• hf-audio/whisper-large-v3-turbo
• （openaiのモデルは名前のないパラメーターを使用するため、動作しません）

テキストから音楽への変換

• haoheliu/audioldm2-text2audio-text2music

ビジョンタスク

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI
• DawnC/PawMatchAI/on_find_match_click - 対話型の犬のおすすめ用

その他の機能

プロンプト

各スペースのプロンプトが生成され、入力する機会が提供されます。多くの場合、スペースには特に役立つラベルなどが設定されていない点に注意してください。Claudeは実際のところ、これを見極めるのが非常に得意です。また、ツールの説明はかなり詳しいものの、Claude Desktopでは表示されません。

リソース

WORK_DIR 内のファイル一覧が返され、利便性のため「Use the file...」というテキストでファイル名も返されます。Claude のコンテキストに何かを追加したい場合は、クリップアイコンを使用してください。それ以外の場合は、MCP サーバーにファイル名を指定してください。Claude はコンテキスト内からリソースを送信できません。

プライベートスペース

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

Claude Desktop の使用

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

• Claude Desktop 0.75 は MCP サーバーからのエラーに応答せず、代わりにタイムアウトするようです。問題が続く場合は、MCP Inspector を使用すると、問題の診断に役立ちます。突然動作しなくなった場合は、HuggingFace ZeroGPU のクォータを使い切った可能性があります。しばらくしてから再試行するか、ホスティング用に独自の Space を設定してください。
• Claude Desktop は 60s のハードタイムアウト値を使用しているようで、UX の管理や接続の維持に Progress Notifications を使用している様子はありません。ZeroGPU スペースを使用している場合、大規模または負荷の高いジョブはタイムアウトする可能性があります。ただし、結果については WORK_DIR を確認してください。生成されていれば、MCP サーバーは引き続き結果を取得して保存します。
• Claude Desktop のサーバーステータスやログなどの報告機能はあまり優れていません。問題の診断には @modelcontextprotocol/inspector を使用してください。

HuggingFace Spaces

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

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