hf-mcp-server packages

Hugging Face 公式 MCP サーバー

Hugging Face 公式 MCP サーバーへようこそ 🤗。LLM を Hugging Face Hub および数千の Gradio AI アプリケーションに接続できます。

MCP サーバーのインストール

以下の手順に従って、利用を開始してください。

Claude Desktop または claude.ai にインストール

こちらをクリックして、Hugging Face コネクターをアカウントに追加してください。

または、https://claude.ai/settings/connectorsに移動し、ギャラリーから「Hugging Face」を追加してください。

claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login

claude mcp add hf-mcp-server \
  -t http https://huggingface.co/mcp \
  -H "Authorization: Bearer <YOUR_HF_TOKEN>"

gemini mcp add -t http huggingface https://huggingface.co/mcp?login

VSCode にインストール

こちらをクリックすると、Hugging Face コネクターをVSCodeに直接追加できます。または、https://code.visualstudio.com/mcpのギャラリーからインストールしてください。

手動で設定する場合や認証トークンを使用する場合は、以下のスニペットをmcp.json設定に追加してください。

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }

インストール後、https://huggingface.co/settings/mcp に移動して、ツールとSpacesを設定してください。

ヒント

URLに?no_image_content=trueを追加すると、Gradio サーバーからImageContentブロックを削除できます。

クイックガイド（リポジトリのパッケージ）

このリポジトリには以下が含まれています。

• (/mcp) MCP サーバーとの統合に使用する、Hub API と検索エンドポイントのMCP実装。
• (/app) エンドポイントをデプロイするためのMCP サーバーとWebアプリケーション。

MCP サーバー

以下のトランスポートに対応しています。

• STDIO
• ステートレス JSON モードの StreamableHTTP（StreamableHTTPJson）

Web アプリケーションと HTTP トランスポートは、デフォルトでポート 3000 で起動します。

StreamableHTTP サービスは /mcp で利用できます。仕様で厳密に定められているわけではありませんが、一般的な慣例です。

公開されている Streamable HTTP のデプロイでは、MCP サーバーカードを /mcp/server-card で提供します。公開カードでは、認証固有のクエリパラメーターを含まない標準の https://huggingface.co/mcp エンドポイントを案内します。ループバック環境および MCP_ALLOWED_HOSTS に明示された Hugging Face 以外のホストでは、それぞれの /mcp エンドポイントを案内します。カードのレスポンスは、ETag によるキャッシュ再検証に対応しています。

/metrics の Web アプリケーションでは、サーバーのステータスと MCP メソッドのメトリクスを確認できます。

Skills タブでは、プロセス内のカタログの健全性と Skills のライブアクティビティを確認できます。期間（15m/1h/24h）、クライアント名／バージョン、メソッド、結果で絞り込めます。メタデータの照会（skills/list、skills/get、ディレクトリの読み取り）と、成功した SKILL.md および補助ファイルのコンテンツ読み取りを区別します。取得されたことは、実行されたことやインストールが完了したことを証明するものではありません。クライアント名／バージョンは自己申告です。アクティビティは 10,000 件、24 時間を上限とし、再起動時にリセットされ、網羅性が不完全な場合はその旨を示します。LOG_SKILL_EVENTS とは独立しており、過去のイベントは設定されたデータセットの skills/YYYY-MM-DD/ ログに残ります。現在、ライブアクティビティが対象とするのは streamableHttpJson トランスポートです。健全性のポーリングによってカタログが読み込まれたり更新されたりすることはなく、マニフェストのバイトサイズ検証がまだ実装されていないことを明示的に警告します。Skills ダッシュボードのテレメトリには、対象 URI、ユーザーハッシュ、セッション ID、ファイル内容は含まれません。

管理用 Web インターフェースは、METRICS_PAGE_PASSWORD を使用して、任意の簡易共有パスワードゲートの背後に配置できます。ブラウザーで / にアクセスすると、/mcp の MCP ウェルカムページにリダイレクトされます。ツールの選択は、任意の Hugging Face ユーザー設定 API と bouquet／mix クエリパラメーターに基づいて、各リクエストごとに個別に解決されます。セキュリティ研究者とボットへの注意：これは意図的に簡易的なものであり、機密データや保護対象データとは見なされません。

?bouquet=openai を使用すると、Hub のファイルシステム、リポジトリの検索、詳細表示と作成、動的 Space、Jobs、サンドボックスの各ツールが利用可能になります。リポジトリの作成、Jobs、動的 Space、サンドボックスの各ツールには Hugging Face 認証が必要です。

ローカルでの実行

npx または docker を使って、MCP サーバーをローカルで実行できます。

npx @llmindset/hf-mcp-server       # Start in STDIO mode
npx @llmindset/hf-mcp-server-http  # Start in stateless Streamable HTTP JSON mode

docker で実行するには：

docker pull ghcr.io/evalstate/hf-mcp-server:latest
docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

上記のすべてのコマンドは、管理用 Web インターフェースを http://localhost:3000/metrics で起動します。ブラウザーで http://localhost:3000/ にアクセスすると、http://localhost:3000/mcp の MCP ウェルカムページにリダイレクトされます。設定オプションについては、[環境変数](#Environment Variables) を参照してください。Docker はデフォルトで Streamable HTTP（JSON RPC）モードになります。

開発

このプロジェクトでは、ビルドと開発に pnpm を使用します。全員が同じ pnpm バージョン（10.12.3）を使うように、Corepack を使用します。

OAuth の検出、動的登録、または Client ID Metadata Document の診断については、 docs/oauth-diagnostics.md を参照し、pnpm oauth:diagnose を実行してください。

ベンチマーク用ハーネス、過去の結果、最適化計画は、別の hf-mcp-optimise ワークスペースで管理されています。

# Install dependencies
pnpm install

# Build all packages
pnpm build

ビルドコマンド

pnpm run clean -> ビルド成果物をクリーンアップ

pnpm run build -> パッケージをビルド

pnpm run start -> MCP サーバーアプリケーションを起動

pnpm run buildrun -> クリーンアップ、ビルド、起動

pnpm run dev -> mcp を監視しながら並行して HMR 対応の開発サーバーを起動

Docker ビルド

イメージをビルドします：

docker build -t hf-mcp-server .

デフォルト設定（ストリーミング HTTP JSON モード）で実行します。ダッシュボードはポート 3000 の /metrics で利用できます。 HTTP クライアントは、Authorization: Bearer ヘッダーに Hugging Face トークンを含める必要があります：

docker run --rm -p 3000:3000 hf-mcp-server

STDIO MCP サーバーを実行します：

docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

TRANSPORT には stdio または streamableHttpJson を指定できます（デフォルト）。

トランスポートエンドポイント

トランスポートの種類ごとに、以下のエンドポイントを使用します：

• ステートレス Streamable HTTP JSON：/mcp
• Streamable HTTP JSON 用 MCP サーバーカード：/mcp/server-card
• STDIO：stdin/stdout を直接使用し、HTTP エンドポイントはありません

環境変数

サーバーは、以下の環境変数に対応しています。

• TRANSPORT：使用するトランスポートの種類（stdio または streamableHttpJson）
• DEFAULT_HF_TOKEN：ローカルの STDIO デプロイで使用するデフォルトトークンです。HTTP トランスポートでは、Authorization: Bearer ヘッダーがないリクエストのフォールバックとして使用されません。
• stdio トランスポートで実行する場合、DEFAULT_HF_TOKEN が設定されていなければ HF_TOKEN が使用されます。
• MCP_ALLOWED_HOSTS：MCP と API のルートで許可する追加の Host のカンマ区切り許可リストです。ループバックホスト localhost,127.0.0.1,::1 は常に許可されます。ホスト名を完全一致で指定するか、*.example.com のように先頭にワイルドカードを付けて指定します。
• HF_API_TIMEOUT：Hugging Face API リクエストのタイムアウト（ミリ秒、デフォルト：12500ms / 12.5 秒）
• USER_CONFIG_API：設定済みの Space を含む、tools/list が返すユーザーごとのディスカバリー投影用のオプション URL です。これらの設定で制御するのは、公開するデプロイ済みツールであり、既知のツールへの直接の tools/call を実行できるかどうかではありません。生成された Gradio エイリアスには、引き続き設定済みの Space マッピングが使用されます。未設定の場合は、変更不能な組み込みデフォルトが使用されます。
• ALLOW_INTERNAL_ADDRESS_HOSTS：アウトバウンドチェック時に、信頼されたドメインの内部／予約済み DNS 解決を許可する、オプションのホスト名カンマ区切り許可リストです（完全一致のホスト名と *. ワイルドカードに対応。例：huggingface.co,*.hf.space）。
• MCP_STRICT_COMPLIANCE：JSON Mode で GET リクエストを 405 で拒否するには True に設定します（デフォルトではウェルカムページを表示します）。
• MCP_STRICT_TOKEN：Streamable HTTP 接続でトークンがない場合、サーバーインスタンスを構築する前に 401 で拒否するには true に設定します。デフォルト（未設定またはその他の値）では、現在の動作が維持され、トークンのないリクエストは匿名のツールセットで続行します。指定されたトークンは whoami による検証に合格する必要があります。無効なトークンは 401 を返し、検証が利用できない場合（ネットワークエラーや上流の障害など）は、リクエストの続行を許可せずに 503 を返します。厳格モードが無効の場合、401 以外の検証失敗では、従来どおりフェイルオープンの動作が維持されます。
• DISABLE_TOOLS：tools/list で非表示にし、呼び出された場合は拒否するツール名のオプションのカンマ区切りリストです。例：hub_repo_search,hf_fs。拒否された呼び出しは、MCP ダッシュボードのツール呼び出し統計ではエラーとして引き続き表示されます。
• DEFINITION_TAGS：定義タグ、タグチェック、および関連するキャッシュヒントを無効にするには off に設定します。対象となる HTTP リクエストではデフォルトで有効です。定義タグを参照してください。
• DEFINITION_TAGS_TTL_MS：対象となるツールリストおよびディスカバリー結果のキャッシュヒント TTL（デフォルト：300000、0 も指定可能）。キャッシュのスコープは常にプライベートです。
• DEFINITION_TAGS_SALT：デプロイ全体で使用するオプションのタグソルトです。変更すると既知のタグが無効になるため、レプリカ間で同じ値を使用してください。
• DEFINITION_TAGS_TEST：ダッシュボードの Caching タブと、/api/definition-tags 配下のランタイムソルト／統計コントロールを有効にするには true に設定します。本番環境では無効のままにしてください。コントロールはプロセスごとに適用され、保護されるのは METRICS_PAGE_PASSWORD が設定されている場合のみです。
• PROXY_TOOLS_CSV：Streamable HTTP プロキシツールのソースを定義するオプションの CSV です（以下を参照）。
• PROXY_TOKEN：PROXY_TOOLS_CSV のスキーマを検出する際の起動時認証にのみ使用するオプションのトークンです。
• GRADIO_SKIP_INITIALIZE：true に設定すると、Gradio MCP 呼び出しでは initialize ハンドシェイクをスキップし、tools/call を直接実行します。
• METRICS_PAGE_PASSWORD：/metrics の管理 Web インターフェースと、その /api/* エンドポイントで使用するオプションの共有パスワードです。未設定または空の場合、インターフェースは公開されたままです。/mcp や /mcp/server-card は保護されません。
• HF_SKILLS_DIR：ビルド済みの SEP-2640 スキルスナップショットを格納するローカルディレクトリです。skills.json には、各スキルの uri、完全な frontmatter、およびファイルごとの {uri,digest} リソースマニフェストが含まれ、展開済みのスキルディレクトリとともに配置されます。HTTP トランスポートでは、サーバーがすべての生 SHA-256 ダイジェストを検証し、実際の SKILL.md の frontmatter を確認してから、すべてのファイルをメモリにアトミックに保持します。各スキルのファイル数は最大 512 個、生コンテンツのサイズは SKILL.md とネストされたファイル／共有ファイルを含めて最大 16 MiB です。いずれかの上限を超えるスナップショットは、最後に検証済みのスナップショットを置き換えずに拒否されます。ディレクトリの読み取りでは空のディレクトリも取得されます。スナップショットの鮮度 TTL は 3 時間です。古くなったスナップショットへのリクエストでは、バックグラウンドでスナップショットを 1 つ読み込み、検証している間、最後に有効だったスナップショットが引き続き使用されます。更新に失敗した場合は、検証済みのスナップショットを保持し、5 分間の再試行待機時間を設けます。HTTP サーバーは skills/list、skills/get、resources/read、およびオプションの resources/directory/read を実装し、有効なスナップショットが利用可能な場合に限り、directoryRead: true を指定して io.modelcontextprotocol/skills を通知します。スキルは、長時間接続する STDIO トランスポートでは公開されません。デフォルトは /mnt/hf-skills/distribution/latest で、hf://buckets/huggingface/skills からマウントされた Hugging Face Space ボリュームでの使用を想定しています。
• LOG_SKILL_EVENTS：LOGGING_DATASET_ID とロギングトークンが設定されている場合、SEP-2640 Skills のプローブについて過去の製品利用状況のログ記録を有効にします（デフォルト：true）。イベントはツールクエリとは別に skills/YYYY-MM-DD/ 配下へ書き込まれ、クライアント／プロトコルの相関情報、成功の有無、所要時間、カーソルの有無、結果数の集計、対象を指定した get／read 操作で要求された skill:// URI が含まれます。カーソル値、frontmatter、リソースコンテンツ、レスポンス本文、エラーメッセージは記録されません。
• SHUTDOWN_GRACE_MS：SIGTERM／SIGINT を受けてからの正常なシャットダウンに許される上限時間（デフォルト：25000）。サーバーは最大 min(5s, grace/3) の間、処理中の HTTP リクエストの完了を待ってから、バッファーされたデータセットログをフラッシュし、その後終了します。プラットフォームの停止タイムアウトより短い値にしてください。
• RUNTIME_METRICS_LOG_INTERVAL_MS：runtime_sample レコード（イベントループの稼働率、CPU、イベントループの遅延、メモリ、接続の再利用、X-Forwarded-For のホップ数）を System データセットストリームに書き込む間隔（デフォルト：60000、0 で無効）。システムイベントのログ記録を有効にする必要があります。同じデータは、ダッシュボードの Process runtime カードにもリアルタイムで表示されます。

管理インターフェースのパスワード（任意）

METRICS_PAGE_PASSWORD に空でない値を設定すると、管理 Web インターフェースとその API エンドポイントで、簡易的な共有パスワードによる保護が有効になります。

• / へのブラウザーアクセスは /mcp にリダイレクトされます。パスワードが受け入れられるまで、/metrics へのアクセスは /metrics/login にリダイレクトされます。
• ログインに成功すると、/metrics にリダイレクトされます。
• ログインに成功すると、署名付きの HttpOnly、SameSite=Lax 属性を持つ 30 日間有効な Cookie が保存されます。HTTPS リクエストでは、Secure Cookie 属性も付与されます。
• /api/transport、/api/sessions、/api/transport-metrics、/api/skills-metrics へのアクセスには、Cookie または有効なスクレイパー認証情報が必要です。
• /mcp と公開されている /mcp/server-card には影響しません。

これは、気軽な閲覧を防ぐことのみを目的としています。ユーザー、ロール、レート制限、監査証跡はありません。また、実際の認証、HTTPS、またはプラットフォーム／リバースプロキシ層でのアクセス制御の代わりにはなりません。 HTTPS がリバースプロキシで終端される場合、アプリケーションが Cookie の Secure 属性を正しく適用できるよう、プロキシは X-Forwarded-Proto を実際のクライアントプロトコルで上書きする必要があります。

Hugging Face Space では、Space の設定でこれを Space secret として設定してください。GitHub Actions のシークレットは、このリポジトリのワークフローから実行中の Space に自動的に渡されません。Hugging Face CLI で設定する場合は、次のコマンドを使用します。

hf spaces secrets add <org>/<space> -s METRICS_PAGE_PASSWORD='<shared-password>'

自動スクレイパーは、ヘッダーでパスワードを送信できます。

curl --fail-with-body --silent --show-error \
  -H "X-Metrics-Password: ${METRICS_PAGE_PASSWORD}" \
  https://your-space.hf.space/api/transport-metrics

簡単な URL ベースのジョブでは、URL エンコードされたクエリパラメーターも使用できます。

curl --fail-with-body --silent --show-error --get \
  --data-urlencode "metrics_password=${METRICS_PAGE_PASSWORD}" \
  https://your-space.hf.space/api/transport-metrics

可能な場合はヘッダーを使用してください。アプリケーション自体は認証情報をログに記録しませんが、クエリー文字列内のパスワードは、リバースプロキシやアクセスログ、監視システム、シェルのプロセス一覧、ブラウザー履歴に保存される可能性があります。

Space から共有 Hugging Face スキルカタログを公開するには、バケットをマウントし、HF_SKILLS_DIR が最新の配布ディレクトリを指すようにします。

hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro
hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest

プロキシツール（CSV 経由の Streamable HTTP）

起動時にプロキシツール定義を読み込むには、PROXY_TOOLS_CSV に HTTPS URL またはローカルファイルパスを設定します。 これらのプロキシサーバーで認証が必要な場合は、PROXY_TOKEN を設定します。ユーザー、デフォルト、ロギング用のトークンは、起動時のプロキシスキーマ検出には使用されません。 サーバーは起動時に各 MCP エンドポイントを 1 回取得し、initialize と tools/list（タイムアウト 10 秒）を実行して、返されたツールを登録します。 ソースの取得に失敗した場合や、ツールが返されなかった場合は、そのソースはスキップされます（起動は失敗しません）。

CSV 形式

tool_name,url,response_type
papers,https://evalstate-hf-papers.hf.space/mcp,SSE
news,https://example.com/mcp,JSON

• tool_name：単一ツールを提供するアップストリームではローカルのツール名、複数のツールを提供するアップストリームではプロキシソースの識別子です。
• url：Streamable HTTP MCP エンドポイントです。
• response_type：旧バージョンとの互換性のためのフィールドです。SSE と JSON のどちらも受け付けます。プロキシ呼び出しでは引き続きアップストリームの Streamable HTTP レスポンスを利用できますが、このサーバーは常にクライアントへ直接 JSON-RPC レスポンスを返します。

ツール名

ツール名は、アップストリームの MCP エンドポイントが返すツール数によって異なります。

• アップストリームのツールが 1 つの場合：公開されるツール名は CSV の 1 列目の値です。
• アップストリームのツールが複数の場合：公開されるツール名はアップストリームのツール名です。

公開するプロキシツール名が登録済みのツール名と重複する場合、そのプロキシツールはスキップされ、警告がログに記録されます。

これらのツール名をブーケやミックスに含めると、tools/list を通じて公開できます。 bouquet=proxy または mix=proxy を指定すると、ベースとなる組み込みツールに加えて、PROXY_TOOLS_CSV から読み込まれたすべてのプロキシツールが公開されます。起動時に設定された既知のプロキシツールへの直接呼び出しは、この検出対象の選択に左右されません。

Dynamic Space のヘルスチェック

monitor/distribution/bin/monitor.py --check は、DYNAMIC_SPACE_DATA で設定されたカタログを対象とする、読み取り専用の CSV ヘルスチェックです。Hub の実行時状態と、実行可能な各 Space の Gradio MCP スキーマをチェックしますが、ツールの呼び出し、Space の再起動、PR の作成は行いません。ローカルで次のように実行します。

pnpm health:dynamic-spaces

Python 3 と標準ライブラリを使用します。カタログの URL は公開されている必要があります。非公開の Space のメタデータとスキーマのリクエストには、まず HF_TOKEN、次に DEFAULT_HF_TOKEN を使用します。スリープ状態の Space は、HEALTH_PROBE_SLEEPING=true にしない限り、起動せずに Hub のメタデータから正常と判断します。

8 時間ごとの修復スケジュールと読み取り専用ダッシュボードについては、monitor/README.md を参照してください。Bucket はレポートとアトミックな台帳を保持します。 HF_TOKEN（設定されていない場合は DEFAULT_HF_TOKEN）は、ヘルスチェックの読み取り、再起動、PR 作成に使用する親 Hub 認証情報です。設定されている場合、両方の修復アクションが有効になります。RESPONSES_API_KEY（またはそのフォールバックである OPENAI_API_KEY）は Doctor モデルの認証情報です。MONITOR_HF_TOKEN が設定されている場合、Doctor にのみ渡される別個の読み取り専用トークンです。公開情報のみを対象とする読み取り専用モニターでは、HF_TOKEN を省略してください。ジョブログには Space ごとに 1 行のステータスと、最後にサマリーが出力されます。

終了コード 0 はすべての Space が正常であることを示し、1 は少なくとも 1 つの Space が異常または劣化していることを示します。カタログまたは設定が無効な場合は、終了コード 2 が返されます。任意の調整用変数は HEALTH_TIMEOUT_SECONDS、HEALTH_ATTEMPTS、HEALTH_RETRY_DELAY_SECONDS、HEALTH_PROBE_SLEEPING です。リトライと手動リセットのポリシーについては、monitor/README.md を参照してください。