Mcp Server For 3x Ui

3x-ui MCP サーバー

3x-ui 用の MCP（Model Context Protocol）サーバーです。3x-ui は Xray/V2Ray プロキシ管理パネルです。3x-ui の HTTP API を MCP ツールとして公開し、LLM がインバウンド、クライアント、ルーティングルール、Xray サービス、サーバー設定を管理できるようにします。

目次

• 機能
• クイックスタート
• プロンプトの例
• エージェントスキル
• 設定
• パネルのバージョン
• MCP ツール
• リソース
• アーキテクチャ
• 開発
• コントリビューション
• ライセンス

機能

• パネル API 全体 — インバウンド、クライアント、グループ、ホスト、ノード、ルーティング、ロードバランサー、ジオデータ、メトリクス、トークン、メンテナンスに対応する 169 個のツールを提供します。ファイル転送とノード同期の 4 つのルートを除き、3x-ui が公開するすべての機能を利用できます（3x-ui v3.3.0 以降 — パネルのバージョンを参照）。
• 2 つの認証方式 — CSRF を使うセッションログイン、または Bearer API トークン（XUI_API_TOKEN）に対応し、どちらの認証情報が期限切れになっても自動的に再認証し、CSRF トークンを更新します。
• メールアドレスをキーにしたクライアント — 1 つのクライアントを複数のインバウンドに関連付けられます。一括作成、調整、有効化、削除に加え、大規模なパネル向けのサーバー側ページングにも対応します。
• 注釈付きツール — すべてのツールで操作の影響を宣言するため、MCP クライアントは実行前に読み取り専用の呼び出しか破壊的な呼び出しかを確認できます。
• デフォルトでは遅延読み込み — 大きなペイロードには概要と resource_link を返し、実際にドキュメントが必要なときにのみ取得します。
• コンテキスト予算を考慮 — XUI_TOOLSETS では指定したツールグループのみを読み込み、各セッションでスキーマが占める領域を削減します。
• エージェントスキルを同梱 — 実際の作業に使える 7 つの手順を用意しています。Xray-core と 3x-ui のソースに照らして検証済みです（エージェントスキルを参照）。
• Stdio トランスポートに対応し、MCP SDK 以外の外部依存関係はありません。

重要

これらのツールは稼働中のプロキシパネルを操作します。破壊的操作の注釈が付いたツールは、クライアントの削除、 トラフィックカウンターのゼロ化、Xray の再起動を行います。Xray を再起動するとすべての接続が切断されます — 一部の操作はパネル全体に適用され、元に戻せません。エージェントには、操作対象を必要な範囲に限定した API トークンを付与し、 一括操作の前にはバックアップを取ってください。

クイックスタート

npx の実行に必要なのは Node 16+ のみです。パッケージには Linux、macOS、 Windows 向けの x64 および arm64 用ビルド済みバイナリが含まれているため、コンパイルも Go ツールチェーンも 不要です。Go がすでにインストールされていれば、go run …@latest も同様に使えます。その他の実行方法を参照してください。

Claude Code

claude mcp add 3x-ui \
  --env XUI_HOST=http://localhost:2053 \
  --env XUI_USERNAME=admin \
  --env XUI_PASSWORD=your-password \
  -- npx -y @pyworkload/3x-ui-mcp

Claude Desktop / Cursor

claude_desktop_config.json（Claude Desktop）または .cursor/mcp.json（Cursor）に追加します。

{
  "mcpServers": {
    "3x-ui": {
      "command": "npx",
      "args": ["-y", "@pyworkload/3x-ui-mcp"],
      "env": {
        "XUI_HOST": "http://localhost:2053",
        "XUI_USERNAME": "admin",
        "XUI_PASSWORD": "your-password"
      }
    }
  }
}

VS Code

.vscode/mcp.json に追加します。

{
  "servers": {
    "3x-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pyworkload/3x-ui-mcp"],
      "env": {
        "XUI_HOST": "http://localhost:2053",
        "XUI_USERNAME": "admin",
        "XUI_PASSWORD": "your-password"
      }
    }
  }
}

その他の実行方法

上記のいずれかの設定で command と args を入れ替えます。

方法	command	args
Go ツールチェーン	go	["run", "github.com/pyworkload/3x-ui-mcp/cmd/xui-mcp@latest"]
ビルド済みバイナリ	/path/to/xui-mcp	—
グローバルインストール	xui-mcp	—

go run …@latest は初回使用時にコンパイルし、以降はキャッシュから実行します。 毎回 npx を使いたくない場合は、npm install -g @pyworkload/3x-ui-mcp を実行すると xui-mcp が PATH に追加されます。

プロンプトの例

接続したら、エージェントに次のようなことを尋ねてみてください。

• 「インバウンド 3 に、容量 10 GB、有効期限 7 日で試用クライアントを 20 件作成して、サブスクリプションリンクを教えてください。」
• 「クォータの 90% を超えているクライアントはどれですか？ すべての有効期限を 30 日延長し、容量を 50 GB 増やしてください。」
• 「104.16.0.0/24 をスキャンして使用可能な REALITY ターゲットを探し、最速のものを VLESS インバウンドに設定してください。」
• 「Warp アカウントを登録して、*.netflix.com の通信を経由させてください。」
• 「誰も接続できません。Xray のログとパネルのログを確認し、各クライアントが最後にオンラインだった時刻を調べてください。」
• 「現在、最も多くのオンラインクライアントにサービスを提供しているノードはどれですか？ また、その負荷はどの程度ですか？」
• 「データベースを Telegram にバックアップしてから、すべてのノードでパネルのセルフアップデートを実行してください。」

エージェントスキル

skills/ には、パネルで実際に行われる作業のための 7 つの手順が含まれています。これらは、ツールのスキーマでは扱えない運用知識をまとめたものです。つまり、どのような順序で作業するか、またパネルが警告しない事柄について説明しています。

スキル	内容
reality-inbound	REALITY のカモフラージュターゲットの選定と検証、キー、shortId、使用不能になったインバウンドの修復
diagnose-connectivity	クライアントが接続できない原因を、最も簡単に確認できるものから調査し、コアのエラー文字列を原因に対応付けます
panel-hardening	管理者パスワードの代わりにスコープを限定したトークンを使用する方法、ローテーション、fail2ban、証明書のピン留め、バックアップ
cdn-fallback	CDN の背後で WebSocket／gRPC／xhttp を使用する方法、およびフォールバックを使ってポート 443 を共有する方法
client-lifecycle	オンボーディング、サブスクリプションリンク、一括更新、レポート、クリーンアップ
smart-routing	ドメインと地域トークンによる分割ルーティング、プロバイダーのアウトバウンド、test_route を使ったルールの検証
multi-node	ノードの追加、TLS の信頼モードと mTLS、選択的な同期、クラスターの監視

cp -r skills/* ~/.claude/skills/     # Claude Code, everywhere
cp -r skills/* .claude/skills/       # this project only

設定

変数	必須	説明	例
XUI_HOST	はい	パネル URL	http://localhost:2053
XUI_USERNAME	はい¹	管理者ユーザー名	admin
XUI_PASSWORD	はい¹	管理者パスワード	admin
XUI_API_TOKEN	いいえ	Bearer API トークン。/panel/api/* の CSRF をバイパスします	eyJ…
XUI_TOOLSETS	いいえ	公開するツールグループ（デフォルト：すべて）	clients,metrics
XUI_BASE_PATH	いいえ	パネルのベースパス（デフォルト：/）	/xui/
XUI_LOG_LEVEL	いいえ	ログレベル（デフォルト：info）	debug、info、warn、error

¹ XUI_USERNAME+XUI_PASSWORD、または XUI_API_TOKEN のいずれかを指定してください。

認証モード（3x-ui は CSRF でパネルを保護し、API トークンをサポートしています）：

• セッション + CSRF（ユーザー名／パスワード）：すべてのツールで機能します。クライアントはログインし、セッションの CSRF トークンを追跡して書き込みリクエストで再送します。トークンが古くなると、自動的に更新します。

• Bearer API トークン（XUI_API_TOKEN）：すべてのリクエストでトークンが送信され、パネルは CSRF なしで /panel/api/* ルートへのアクセスを許可します。v3.3.0 以降では、この範囲に設定や Xray テンプレートを含む、ここに記載されたすべてのツールが含まれます。 パネルの Settings → Security → API Token からトークンを作成してください。

  v3.7.0 以降、トークンにはスコープと有効期限を設定できるため、このサーバーには admin スコープを指定してください。他の 2 つは適しません。monitor はステータスとメトリクスのルートに限定された許可リストで、ここに記載されたツールのうち対象となるのは server_status と get_xray_versions だけです。node-sync はパネルからノードへの通信に限定された許可リストです。作成時に平文のトークンが表示されるのは一度だけで、パネルには SHA-256 ハッシュが保存されます。また、CLI の x-ui setting -getApiToken は現在、新しいトークンを発行するのではなく、共有の cli-fallback トークンをローテーションします。そのため、再実行すると、以前に配布したトークンは無効になります。

  v3.8.0 以降、パネルが拒否するトークンへの応答は、以前のように 404 に見せかけられるのではなく、401 になります。パネルはその後もセッションを確認するため、認証情報も設定されている場合、クライアントはログインして再試行し、トークンが拒否されたという警告をログに記録します。トークンだけを設定している場合、トークン名を含むエラーで呼び出しが失敗します。XUI_BASE_PATH が誤っている場合は引き続き 404 になるため、これで区別できるようになりました。

ツールセットの絞り込み： 169 個すべてのツールスキーマを合わせると、各セッションのモデルコンテキストを約 29k トークン使用するため、絞り込む価値があります。XUI_TOOLSETS を使うと、必要なグループだけを読み込めます：inbounds、clients、server、xray、metrics、groups、geodata、hosts、nodes、tokens、providers、maintenance、または all。XUI_TOOLSETS=clients,metrics を指定すると、約 7.5k トークンで 47 個のツールを使用できます。不明な名前を指定すると、何も読み込まずに続行するのではなく、起動時にエラーになります。

パネルのバージョン

3x-ui v3.3.0 以降が必要です。このリリースでは、設定と Xray のエンドポイントが /panel/setting/* および /panel/xray/* から /panel/api/ 配下に移動しました（上流の c6f15cd5 による、文書化された後方互換性のない変更です）。このサーバーは現在の構成を対象としています。

古いパネルでも、インバウンド、クライアント、サーバーのツールは引き続き機能しますが、設定や Xray テンプレートを扱うものは HTTP 404 を返します。v3.2.8 以前のパネルでは、代わりにリリース v0.2.0 を使用してください。

いくつかのツールは v3.3.0 より後に追加されたエンドポイントをラップしており、以下に記載されたバージョンより古いバージョンでは 404 を返します。

ツール	必要なバージョン
get_balancers、set_balancer_override、test_route	v3.3.1
scan_reality_target、scan_reality_targets、get_all_inbound_links	v3.4.2
可観測性、クライアントグループ、クライアント状態の一括操作、インバウンドのプロジェクションとフォールバック	v3.5.0
ホストグループ、API トークン、クライアントのエクスポート／インポート、外部リンク、Warp、NordVPN	v3.5.0
マルチノードツール	v3.5.0
メンテナンス、証明書ヘルパー、クラスターのクライアントビュー、test_outbounds	v3.5.0
ジオデータ、HWID デバイス、get_clients_by_telegram_id、set_inbound_sub_sort_index	v3.7.0
サブスクリプションバランサー、PIA、reload_node_mtls_client、トークンの scope／expires_at	v3.7.0
validate_regex、get_factory_defaults、get_panel_update_status、get_amneziawg_logs	v3.7.0
preview_client_renewal、reset_weekday クライアントパラメーター	v3.9.0
manage_warp の regMasque アクション、MASQUE インバウンド	v3.10.0

最後の 2 行は、パネル独自の生成済み openapi.json の範囲に限られます。このファイルが利用できるのは v3.5.0 以降のみのため、該当するルートの一部はそれ以前から存在していた可能性があります。

v3.8 ではルートは追加されませんでした。 変更されたのは JSON の形式です。v3.3.1 以降、パネルはインバウンドの settings、streamSettings、sniffing を、旧バージョンで送信されていた JSON エンコード文字列ではなく、ネストされたオブジェクトとして出力します。また、リリースのたびにインバウンドとクライアントに列が追加されています。そのため、このサーバーではどちらのボディも構造体としてモデル化しなくなりました。update_inbound と update_client は現在の行をマップに読み込み、パネルがリクエストごとに再計算するフィールドだけを削除して、指定されたパラメーターを重ね合わせます。新しいパネルで追加されたフィールドは、そのまま引き継がれ、次回の更新時に暗黙に消去されることはありません。ただし、引き継がれることと設定可能であることは同じではありません。そのため、これらのリリースで追加されたクライアント列、すなわち HWID 制限、クライアントごとのリセットサイクル、VLESS のリバースタグ、MTProto、WireGuard、AmneziaWG のピア設定には、add_client と update_client の両方に専用のパラメーターがあります。完全な一覧は xui://docs/client-fields リソースにあります。

v3.9.0 ではルートが 1 つ追加されました — 更新プレビューです。また、インバウンド更新で変更できる内容も変わりました。inbounds/update はボディの内容にかかわらず、保存済みのクライアントリストとインバウンドの enable フラグを維持するようになったため、update_inbound でインバウンドを無効にしたり、クライアントを編集したりすることはできなくなりました。これらの操作には set_inbound_enable とクライアントツールを使用してください。旧バージョンのパネルでも、これらの方法のほうが安全です。同じリリースでは、週次のクォータ更新も追加されました（reset および reset_day とは併用できません。update_client は変更前のモードをクリアします）。また、allow_private が設定されていない場合、get_remote_cert_hash はプライベートアドレスやループバックアドレスのターゲットを拒否します。

v3.10.0 ではルートは追加されませんでした — 追加されたのは Warp の新しいアクションと新しいプロトコルです。manage_warp では、action=regMasque を指定して MASQUE 経由で Warp デバイスを登録できます。パネルには何も保存されず、warp-masque アウトバウンド用の秘密鍵、アドレス、エンドポイントが返されます。MASQUE インバウンドでは、メールアドレスとパスワードでクライアントを認証します。password を指定せずに add_client を呼び出すと、パネルがパスワードを生成します。メールアドレスに : を含めることはできません。同じリリースで、クライアントの WireGuard ピア列（private_key、public_key、pre_shared_key、allowed_ips、keep_alive）は、そのクライアントが属する WireGuard／AmneziaWG インバウンドの下に移動しました。該当するインバウンドがないクライアントでは、update_client は成功しても、パネルは保存済みの値を維持します。バランサーのオーバーライドは、ルーティングの再読み込み後も（コアの再起動ではなく）保持されるようになりました。また、Shadowsocks-2022 の鍵長の誤り、4 バイト未満のマスクパスワード、解析できないレポート、LDAP cron など、Xray が実行できない設定をパネルが拒否するようになりました。v3.10.2 では API に変更はありませんでした。 現在のパネルリリースである v3.10.2（それ以前は v3.9.0 および v3.8.5）でテスト済みです。すべてのツールを稼働中のパネルに対して実行しました。読み取り、書き込み、ノードとして登録された 2 台目のパネルに対するノードツール、実際にリストを提供する URL に対するアウトバウンドサブスクリプションツールが対象です。4 つのツールは、このサーバーでは用意できない設定を必要とします。test_smtp と test_telegram_bot は認証情報を、delete_client_device はクライアントアプリが登録したデバイスを、get_node_cert_fingerprint は HTTPS ノードを必要とするため、これらについてはパネルに到達して応答を受け取ることを確認しており、成功することまでは確認していません。読み取り・変更・書き込みの契約は、更新前後のインバウンド全体とクライアント全体を差分比較する統合テスト（make test-panel）で固定しています。

MCP ツール

すべてのツールには、パネルへの影響（読み取り専用、追加、破壊的、サービス中断）と、パネル外部のホストに接続するかどうかが注記されています。MCP クライアントはこれらのヒントを使って、安全な呼び出しを自動承認し、それ以外の呼び出しの前に確認を求めます。

インバウンド管理

15 個のツール — CRUD、有効化の切り替え、トラフィックのリセット、フォールバック、一括削除、リンク

ツール	説明
list_inbounds	すべてのインバウンド接続を一覧表示します
get_inbound	ID でインバウンドを取得します
create_inbound	新しいインバウンドを作成します
update_inbound	既存のインバウンドを更新します
delete_inbound	インバウンドを削除します
set_inbound_enable	設定を書き換えずにインバウンドを有効化／無効化します
reset_inbound_traffic	1 つのインバウンドのトラフィックカウンターをゼロにします
delete_all_inbound_clients	インバウンドは維持したまま、そのインバウンドからすべてのクライアントを削除します
bulk_delete_inbounds	1 回の呼び出しで複数のインバウンドを削除します
get_all_inbound_links	接続 URL の数を返し、全リストへのリンクを取得します（full=true の場合は URL をインラインで含めます）
list_inbounds_slim	クライアント配列を縮小したインバウンドを返します。大規模なパネル向けの低コストな一覧取得です
get_inbound_options	選択用の投影：id、remark、tag、protocol、port、機能フラグ
get_inbound_fallbacks	マスターの VLESS/Trojan TCP-TLS インバウンドに設定されたフォールバックルールを取得します
set_inbound_fallbacks	フォールバックリスト全体を置き換えます（Xray を再起動します）
set_inbound_sub_sort_index	サブスクリプション出力におけるインバウンドの位置を設定します

### クライアント管理

クライアントはメールアドレスをキーとするエンティティで、複数のインバウンドに同時に紐付けられます。

41 tools — メールアドレスによる CRUD、紐付け／解除、一括操作、通信量、デバイス、オンライン状態

Tool	説明
add_client	クライアントを作成し、1 つ以上のインバウンド（inbound_ids）に紐付けます
update_client	メールアドレスでクライアントを更新します（指定されたフィールドのみ変更され、UUID は保持されます）
delete_client	メールアドレスでクライアントを削除します（keep_traffic は任意です）
get_client	メールアドレスで、クライアントの全設定とインバウンドへの紐付けを取得します
list_clients	ページ分け、検索、フィルタリングに対応したクライアント一覧
attach_client	既存のクライアントを追加のインバウンドに紐付けます
detach_client	指定したインバウンドからクライアントの紐付けを解除します
bulk_create_clients	同じインバウンドに複数のクライアントを作成します
bulk_delete_clients	メールアドレスを指定して複数のクライアントを削除します
get_client_traffic	メールアドレスでクライアントの通信量統計を取得します
get_client_ips	クライアントが使用した IP アドレスを取得します
clear_client_ips	記録されたクライアントの IP アドレスを消去します
reset_client_traffic	メールアドレスでクライアントの通信量カウンターをリセットします
reset_all_traffics	すべてのインバウンドの通信量カウンターをリセットします
reset_all_client_traffics	すべてのクライアントの通信量をリセットします（パネル全体）
bulk_reset_traffic	指定したクライアントの通信量をリセットします
delete_depleted_clients	通信量を使い切った、または期限切れのクライアントを削除します（パネル全体）
get_online_clients	現在接続中のクライアント一覧
get_last_online	すべてのクライアントの最終オンライン時刻
update_client_traffic	クライアントのアップロード／ダウンロードのバイトカウンターに特定の値を設定します
get_subscription_links	サブスクリプション ID で提供される接続 URL を JSON 形式で取得します
get_client_links	メールアドレスでクライアント 1 人分の接続 URL を、インバウンドごとに取得します
get_happ_link	Happ アプリ向けに、クライアントのサブスクリプションをラップした暗号化 happ://crypt5 リンク
preview_client_renewal	クォータ更新スケジュールが次に実行される時刻をパネルのタイムゾーンで表示します。何も保存しません
get_clients_by_telegram_id	Telegram ユーザー ID でクライアントを検索します
list_client_devices	クライアントに登録されている HWID デバイスを一覧表示します
delete_client_device	登録済みデバイスを 1 台削除し、HWID スロットを空けます
clear_client_devices	クライアントの登録済みデバイスをすべて削除します
bulk_enable_clients	複数のクライアントを有効化します。所有するインバウンドごとに 1 回書き換えます
bulk_disable_clients	複数のクライアントを無効化します。所有するインバウンドごとに 1 回書き換えます
bulk_adjust_clients	複数のクライアントの有効期限とクォータを調整します。一括更新機能です
delete_orphan_clients	どのインバウンドにも紐付いていないクライアントと、そのレコードを削除します
export_clients	クライアント数と完全なエクスポートへのリンクを取得します（full=true を指定すると内容を直接含めます）
import_clients	エクスポートされた配列からクライアントを作成します。既存のメールアドレスはスキップされます
set_client_external_links	クライアントの外部リンクとサブスクリプションを置き換えます
list_clients_paged	クライアント一覧のサーバー側でのフィルタリング、並べ替え、ページ分け
bulk_attach_clients	複数のクライアントを複数のインバウンドに同時に紐付けます
bulk_detach_clients	複数のクライアントを複数のインバウンドから同時に切り離します
get_active_inbounds	通信量があったインバウンドのタグをノードごとにまとめて取得します
get_online_clients_by_node	オンライン中のクライアントを、接続先ノードごとにまとめて取得します
get_client_ips_by_node	クライアントごとの送信元 IP アドレスを、それを検知したノードごとにまとめて取得します

### サーバー管理

14 個のツール — ステータス、ログ、Xray サービスの制御、キー生成、REALITY スキャン

ツール	説明
server_status	サーバーのシステムステータスを取得します（CPU、RAM、ディスク、稼働時間）
restart_xray	Xray サービスを再起動します
stop_xray	Xray サービスを停止します
get_xray_config	実行中の Xray 設定の概要と、完全な JSON へのリンクを取得します（full=true を指定するとインラインで表示します）
get_xray_versions	利用可能な Xray のバージョンを一覧表示します
install_xray	指定した Xray のバージョンをインストールします
get_logs	パネルサービスのログを取得します
get_xray_logs	Xray コアのログを取得します
get_settings	パネルの設定を取得します
get_default_xray_config	デフォルトの Xray 設定を取得します
restart_panel	3x-ui パネルを再起動します
generate_key	UUID、X25519（Reality）、VLESS 暗号化、ML-KEM-768、ML-DSA-65 のキー素材を生成します
scan_reality_target	REALITY の候補を 1 つ調査し、使用可能かどうかを報告します
scan_reality_targets	ドメイン、IP、CIDR 範囲を調査し、実現可能性とレイテンシで順位付けします

Xray 設定

21 個のツール — テンプレート、ルーティングルール、アウトバウンド、バランサー、アウトバウンドサブスクリプション

ツール	説明
get_xray_template	テンプレートの概要と、完全な JSON へのリンクを取得します（full=true を指定するとインラインで表示します）
update_xray_template	Xray の JSON テンプレートを更新します
get_routing_rules	すべてのルーティングルール（および参照先のバランサー）を一覧表示します
add_routing_rule	ルーティングルールを追加します
remove_routing_rule	インデックスを指定してルーティングルールを削除します
update_routing_rule	インデックスを指定してルーティングルールを更新します
get_outbounds	すべてのアウトバウンドを一覧表示します
get_outbounds_traffic	アウトバウンドのトラフィック統計を取得します
reset_outbound_traffic	アウトバウンドタグのトラフィックをリセットします
test_outbound	アウトバウンドの接続をテストします
get_balancers	バランサーの定義と、実行中のコアにおける現在の状態を取得します
set_balancer_override	バランサーを 1 つのアウトバウンドに固定するか、戦略に戻します
test_route	合成接続に対して、コアがどのアウトバウンドを選択するかを確認します
list_outbound_subs	アウトバウンドサブスクリプション（追加のアウトバウンドを提供するリモート URL）を一覧表示します
preview_outbound_sub	サブスクリプション URL を保存せずに解析します
create_outbound_sub	アウトバウンドサブスクリプションを追加します
update_outbound_sub	サブスクリプションを更新します（指定したフィールドのみ変更されます）
refresh_outbound_sub	サブスクリプションを今すぐ再取得し、そのアウトバウンドを返します
move_outbound_sub	サブスクリプションの優先順位を上下に変更します
delete_outbound_sub	アウトバウンドサブスクリプションを削除します

ホストグループ

ホストグループは、CDN のホスト名、2 つ目のポート、異なる SNI などの外部アドレスで 1 つ以上のインバウンドを公開し、パネルはそれらに対応するサブスクリプションリンクを生成します。グループは文字列の group_id で指定します。

11 個のツール — CRUD、並べ替え、一括状態変更

ツール	説明
list_hosts	すべてのインバウンドに属するホストグループをすべて取得します
get_host_group	ID を指定して 1 つのグループを取得します
get_inbound_hosts	1 つのインバウンドに関連付けられたグループを取得します
list_host_tags	グループ全体で使用されているタグを重複なしで一覧表示します
add_host_group	一連のインバウンドを対象にグループを作成します
update_host_group	省略したフィールドを保持したままグループを更新します
delete_host_group	グループとそのホストを削除します
set_host_group_enable	1 つのグループを有効または無効にします
reorder_host_groups	グループの表示順を設定します
bulk_delete_host_groups	複数のグループを一度に削除します
bulk_set_host_groups_enable	複数のグループの有効・無効を一度に切り替えます

add_host_group と update_host_group では、通常グループの作成に使うフィールドを指定できます。それ以外の項目（mux、sockopt、ECH、final mask）は raw_json で HostGroup 全体を送信します。

サブスクリプションのロードバランサー

クライアント側のロードバランサーです。いずれかのインバウンドに属する各クライアントのJSONサブスクリプションに表示され、クライアントアプリが戦略に基づいてサーバーを選択します。Xray内部で稼働するルーティング用ロードバランサーを報告するget_balancersとは異なります。

4 tools — 並び順に沿ったCRUD

ツール	説明
list_sub_balancers	並び順に沿ったすべてのサブスクリプション用ロードバランサー
create_sub_balancer	一連のインバウンドにロードバランサーを追加
update_sub_balancer	省略したフィールドを保持したまま更新
delete_sub_balancer	ロードバランサーを削除

API トークン

4 tools — 発行、無効化、削除

ツール	説明
list_api_tokens	トークンのメタデータ。トークンの値自体は返されません
create_api_token	スコープ付きトークンを発行。平文が表示されるのは一度だけです
set_api_token_enabled	トークンを削除せずに無効化、または再有効化
delete_api_token	トークンを完全に削除

delete_api_tokenとset_api_token_enabledには、保存済みのトークンのscopeを指定します。一致しない場合、パネルは処理を拒否するため、IDを推測してトークンの状態を変更することはできません。

アウトバウンドプロバイダー

Cloudflare Warp、NordVPN、PIAにはそれぞれ読み取りツールと書き込みツールが用意されているため、国の一覧を問い合わせる操作と認証情報を消去する操作を区別できます。

6 tools — プロバイダーごとに読み取りツールと書き込みツール

ツール	説明
get_warp_data	Warpアカウントの状態、または保存済みのWireGuard設定
manage_warp	登録（WireGuardまたはMASQUE）、IPのローテーション、ライセンスの適用、ローテーションの設定、または消去
get_nordvpn_data	国、国別のサーバー、または保存済みのアカウント
manage_nordvpn	トークンで登録、キーを設定、または消去
get_pia_data	地域、地域別のサーバー、または保存済みのアカウント
manage_pia	ログイン、サーバーに対するキーの登録、または消去

パネルのメンテナンス

19 tools — ヘルスチェック、証明書、地理データファイル、セルフアップデート、バックアップ、統合テスト

ツール	説明
get_fail2ban_status	このホストでクライアントごとのIP制限を適用できるかどうか
get_web_cert_files	このパネル独自のTLS証明書とキーのパス
get_cert_hash	ピン留め用の証明書のSHA-256
get_remote_cert_hash	リモートサーバーの現在の証明書のSHA-256
generate_ech_cert	1つのSNIに対するECHキーペアと設定リスト
update_geofile	最新のGeoIP/GeoSiteデータファイルをダウンロード
get_panel_update_status	直近のパネルのセルフアップデートの結果
set_update_channel	stableチャンネルとdevチャンネルを切り替え
update_panel	パネルをセルフアップデート（再起動されます）
get_amneziawg_logs	AmneziaWGピアのアクティビティとイベントをリアルタイムで確認
get_node_descendants	クラスターツリーでこのパネルの下位にあるノード
get_client_ips_table	IP制限に使用する集約済みクライアントIPテーブル
backup_to_telegram	データベースのバックアップを管理者のTelegramチャットに送信
test_smtp	段階ごとのレポートを含むSMTPテスト
test_telegram_bot	設定済みのボット経由でテストメッセージを送信
validate_regex	パネルのGo RE2エンジンでパターンをコンパイル
get_default_settings	新規インストール時に算出される設定をプレビュー
get_factory_defaults	各設定キーに適用される出荷時の既定値
update_admin_credentials	パネル管理者のユーザー名とパスワードを変更

update_admin_credentialsを実行すると、このサーバー自身が使用する認証情報が無効になります。XUI_USERNAME / XUI_PASSWORDを更新してからサーバーを再起動するか、先にAPIトークンに切り替えてください。

マルチノード

ノードとは、このパネルが制御する別の 3x-ui パネルです。インバウンドとクライアントがノードにプッシュされ、ノードのトラフィックがこのパネルに取り込まれます。これらの呼び出しの大半は、このパネルだけでなくノード自体に対して行われます。

16 tools — CRUD、プローブ、mTLS、ノードパネルの更新

Tool	Description
list_nodes	設定済みノードのヘルス状態、件数、最終ハートビート
get_node	1 つのノードの接続詳細と同期状態
get_node_history	1 つのノードの CPU またはメモリの履歴
get_node_web_cert	ノード上に存在する証明書と鍵のパス
test_node	接続情報を保存せずにプローブ
list_node_inbounds	選択的同期に使用する、ノードで利用可能なインバウンド
get_node_cert_fingerprint	ピン留め用の、ノードのリーフ証明書の SHA-256
add_node	ノードを登録（保存前にプローブ）
update_node	ノードを更新し、省略したフィールドは保持
set_node_enable	ノードとのトラフィック同期を一時停止または再開
probe_node	登録済みノードをプローブし、キャッシュされたヘルス状態を更新
delete_node	ノードを削除。そのインバウンドは移行されません
get_node_mtls_ca	このパネルのノード認証用 CA。初回呼び出し時に発行
set_node_mtls_trust_ca	ノードとして動作する際に、このパネルが信頼する CA
reload_node_mtls_client	再起動せずに、ローテーションされたクライアント証明書を適用
update_node_panels	指定したノードで 3x-ui のセルフアップデーターを実行

v3.6.0 以降、ノード API トークンは書き込み専用です。パネルはトークンが設定されているかどうかだけを報告するため、新しいトークンを渡さない限り、update_node はトークンを省略します。mTLS に移行したノードが古いトークンを破棄するには、clear_api_token を使用します。

クライアントグループ

グループは、クライアントレコードと、そのクライアントを所有する各インバウンドの設定の両方に記録されるラベルです。パネルは 1 つのトランザクションで両者を同期させます。

8 tools — CRUD と一括メンバー管理

Tool	Description
list_client_groups	空のグループを含む、メンバー数付きのすべてのグループ
get_client_group_emails	1 つのグループに属するメールアドレス。一括操作への入力として使用
create_client_group	空の選択可能なグループを作成
rename_client_group	グループの名前を変更し、すべてのメンバーの参照先を更新
delete_client_group	クライアントを保持したままグループを削除
add_clients_to_group	多数のクライアントに 1 つのグループを設定
remove_clients_from_group	多数のクライアントのグループラベルを解除
reset_client_group_traffic	クライアントごとのカウンターは稼働させたまま、グループカウンターをゼロにリセット

可観測性

6 tools — メトリクス履歴、オブザーバトリー、アップデート確認

Tool	Description
get_metrics_history	1 つのホストメトリクス（cpu、mem、netUp/Down、online、load）の時系列データ
get_xray_metrics	Xray のランタイムメトリクスの状態と現在の expvar 値
get_xray_metrics_history	1 つの Xray ランタイムメトリクスの時系列データ
get_xray_observatory	最新のアウトバウンドごとのレイテンシとヘルス状態のスナップショット
get_xray_observatory_history	1 つのアウトバウンドタグのプローブ結果の推移
get_panel_update_info	より新しい 3x-ui リリースがあるかどうか

履歴ツールは秒単位の bucket を受け取り、常に 60 個のサンプルを返すため、バケットによって対象期間も決まります。2（2 分）、30（30 分）、60（1 時間）、180（3 時間）、360（6 時間）、720（12 時間）、1440（24 時間）、2880（2 日）、10080（7 日）です。

地理データ

4 tools — 地理データベースの参照、ルーティングトークンの検証

Tool	Description
list_geodata_files	Xray のアセットフォルダー内にある地理データベース。レイアウトとカテゴリ数も表示します
list_geodata_categories	1 つのデータベース内のカテゴリ。エントリー数と属性も表示します
list_geodata_entries	カテゴリ内のルール。型付きドメインまたは CIDR です
validate_geodata_tokens	解決できないルーティングトークンと、その理由を報告します

意図的にラップしていないもの： server/getDb、server/getMigration、server/importDB はデータベースファイルを添付ファイルやマルチパートアップロードとして受け渡すため、ここではなくブラウザーやバックアップスクリプトで扱うものです。 inbounds/pushClientTraffics と POST server/clientIps はノード同期の受信側です。ノードがリクエストを受け取るエンドポイントであり、クライアントが呼び出すものではありません。

リソース

呼び出し元がすべての結果を必要としているかどうかにかかわらず、ツールの結果はコンテキストを消費します。 リソースは遅延取得用です。それぞれ resources/list の1行分のコストがかかり、URI を要求されたときにのみ読み込まれます。 最もデータ量の多い3つのツールは、要約と対応するリソースへの resource_link を返します。実行中の Xray 設定は約 9k 文字ですが、その要約は 500 文字未満です。

URI	Contents
xui://docs/inbound-settings	settings、streamSettings、sniffing の JSON と、プロトコルごとの例
xui://docs/client-fields	各クライアントフィールドの意味と使用単位
xui://xray/config	コアが現在実行している設定
xui://xray/template	保存済みテンプレート：routing、balancers、outbounds、DNS
xui://inbounds	すべてのインバウンドと、その設定およびクライアントごとの統計情報
xui://inbounds/links	すべてのクライアントの接続 URL
xui://clients/export	{client, inboundIds} 形式のすべてのクライアント（認証情報を含む）
xui://inbound/{id}	数値 ID で指定した1つのインバウンド
xui://client/{email}	メールアドレスで指定した1つのクライアントレコード

2つの xui://docs/… リソースは静的なリファレンステキストなので、読み込んでもパネルへの呼び出しは発生しません。

アーキテクチャ

cmd/xui-mcp/main.go        Entry point, config loading, signal handling
internal/config/            Configuration from environment variables
internal/xui/              HTTP client with session management
internal/handler/          MCP tool definitions and request handlers

開発

make test       # Run tests
make lint       # Run golangci-lint (config in .golangci.yml)
make fmt        # Format code
make build      # Build binary

コントリビューション

バグ報告、パネルのバージョンに関する情報、プルリクエストを歓迎します。セットアップ方法、CI で実行されるチェック、新しいツールが従う必要のあるパネルの規約については、CONTRIBUTING.md をご覧ください。 参加にあたっては Code of Conduct が適用されます。脆弱性については、issue を作成せず、SECURITY.md の手順に従ってください。 ツール数や必要なパネルのバージョンを含む、各リリースの変更内容は CHANGELOG.md に記載されています。

ライセンス

MIT