remnawave-mcp
remnawave-mcp
Remnawave パネル API 用の MCP サーバーです。
@folexzスコープで公開されています。npm 上のスコープなしのremnawave-mcpという名前は、Remnawave 2.7.4 を対象とした無関係なプロジェクトに属しており、2.8.0+ では動作しません。
npx -y @folexz/remnawave-mcp # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITEこれは、Remnawave API v3.3.2 の 28 コントローラにわたる全 205 オペレーション(ユーザー、ノード、ホスト、設定プロファイル、スクワッド、サブスクリプション、ノードプラグイン、インフラ課金、システム統計)をカバーしています。手書きではなく、パネル自身の OpenAPI ドキュメントから生成されています。新しい仕様を npm run build-spec に指定すれば、ツールの表面もそれに追従します。
ハイライト
仕様駆動で、自己更新型。
npm run update-specは Remnawave が公開している最新の OpenAPI ドキュメントを取得し、カタログを再構築します。各ツールの入力スキーマは、オペレーションのパラメータとリクエストボディから直接取得されます。API について手書きで記述されたものは一切なく、再構築時には追加・削除・名前変更された各オペレーションを名前付きで示す diff が出力されるため、バージョンアップでツールが静かに失われることはありません。コンテキストコストを制限。 205 個の型付きツールは、リクエストのたびに
tools/listで約 39k トークンを消費します。デフォルトのプロファイルは 5 ツール(約 1.4k トークン)を公開し、それでもすべてのオペレーションに到達できます — 205 ツールでない理由 を参照。2 トークンの最小権限認証。 読み取りトークンと、オプションの書き込みトークン。
GETは読み取りトークンを使用し、POST/PATCH/PUT/DELETEは書き込みトークンを使用します。書き込みトークンがない場合、変更を伴うツールは一切登録されません — サーバーは物理的に読み取り専用になります。稼働中のパネルに対するガードレール。 変更操作は最小間隔で直列化され、バックオフ付きで再試行されます。これは、設定を書き込むたびにパネルが全ノードに設定をプッシュし、Xray を再起動するためです。一括操作と削除操作にはさらに
confirm: trueが必要です。フィールドノートを組み込み。 以下の注意点は、影響を受けるオペレーションに添付されるため、ツールの説明と
remnawave_describe_operationの出力に表示されます。成功できないリクエストは送信しない。 16 のエンドポイント(認証、パスキー、API トークン管理)は、ログイン済みの管理者 JWT にのみ提供され、API トークンは拒否されます。これらは仕様から検出され、送信される代わりに説明付きでローカルで拒否されます。
脱出ハッチ。
remnawave_request_read/remnawave_request_writeは、未文書のルートや OpenAPI が表現できないクエリ構文を含む任意のパスに到達できます。
Related MCP server: mcp-remnawave
要件
Node.js ≥ 18
HTTPS で到達可能な Remnawave パネル(3.x)
パネルからの API トークン: 設定 → API トークン。Remnawave 3.x はスコープ付きトークンをサポートしているため、読み取りスコープのトークンと、変更を有効にする場合は書き込みスコープのトークンを発行してください。
インストール
簡単な方法は npx です — Claude Code に登録 を参照。ソースから実行する場合:
git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build設定
すべての設定は MCP ホストが提供する環境変数です。ファイルは読み取られません。
変数 | 必須 | デフォルト | 説明 |
| はい | — | パネルのオリジン。例: |
| はい | — | 読み取りトークン。エイリアス: |
| いいえ | — | 書き込みトークン。省略すると読み取り専用になります。 |
| いいえ |
|
|
| いいえ | — | カンマ区切りのコントローラスラッグ。プロファイルの型付きツール選択を上書きします。 |
| いいえ |
| これより大きい入力スキーマは |
| いいえ |
| 2 つの変更操作の間の最小間隔。 |
| いいえ |
| トランスポート障害、429、5xx での再試行回数。 |
| いいえ |
| リクエストごとのタイムアウト。 |
| いいえ |
|
|
| いいえ |
|
|
Claude Code に登録
読み取り専用(推奨デフォルト):
claude mcp add remnawave --scope user \
--env REMNAWAVE_BASE_URL=https://panel.example.com \
--env REMNAWAVE_API_TOKEN_READ=your_read_token \
-- npx -y @folexz/remnawave-mcp@latest変更を有効にし、日常的なコントローラの型付きツールを使用する場合:
claude mcp add remnawave --scope user \
--env REMNAWAVE_BASE_URL=https://panel.example.com \
--env REMNAWAVE_API_TOKEN_READ=your_read_token \
--env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
--env REMNAWAVE_TOOL_PROFILE=core \
-- npx -y @folexz/remnawave-mcp@latest@latest により、npx は起動のたびに最新の公開バージョンを解決します。ローカルビルドを実行するには、コマンドを node /absolute/path/to/remnawave-mcp/dist/index.js に置き換えてください。
Claude Desktop / その他の MCP クライアントに登録
{
"mcpServers": {
"remnawave": {
"command": "npx",
"args": ["-y", "@folexz/remnawave-mcp@latest"],
"env": {
"REMNAWAVE_BASE_URL": "https://panel.example.com",
"REMNAWAVE_API_TOKEN_READ": "your_read_token"
}
}
}
}205 ツールでない理由
tools/list はリクエストのたびにモデルに再送信されるため、そのシリアライズサイズは永続的なコンテキスト税になります。この仕様で測定した結果(npx tsx scripts/tool-stats.ts):
プロファイル | ツール数(読み取り+書き込み) |
| ≈トークン | ツール数(読み取り専用) | ≈トークン |
| 5 | 5.6 KB | ~1.4k | 4 | ~1.2k |
| 91 | 71 KB | ~17.8k | 38 | ~5.9k |
| 210 | 156 KB | ~39k | 92 | ~13.9k |
Remnawave の DTO が full をこれほど高価にしている理由です。1 つの逆参照されたホストオブジェクトは、それだけで約 30 KB の JSON Schema になります。これは、すべてのインバウンドとセキュリティのバリアントを埋め込むためです。
したがって、サーバーは「オペレーションごとに 1 ツール」と「1 つの鈍いディスパッチャ」のどちらかを選ぶのではなく、両方を提供し、プロファイルがどれだけ宣伝するかを決定します:
カタログツール(常時オン、3 ツール)。
remnawave_list_operationsはカタログを閲覧・検索し、オペレーションごとに 1 行のコンパクトな行を返します。remnawave_describe_operationは 1 つのオペレーションの完全な JSON Schema とフィールドノートを返します。remnawave_callは 205 のいずれかを名前で実行します。通常のループは list → describe → call で、API がどれだけ大きくなっても同じ 1.4k トークンで済みます。これは、エージェントハーネスがツールスキーマを遅延ロードするのと同じアイデアです。型付きツール(プロファイル選択)。 実際に操作するコントローラのオペレーションごとに 1 つの生成ツール。
coreはユーザー、ノード、ホスト、設定プロファイル、内部スクワッド、システム、および 2 つの一括操作コントローラをカバーします。fullはすべてをカバーします。minimalはなし。REMNAWAVE_MAX_SCHEMA_BYTESを超えるスキーマは、トップレベルのフィールドを保持し、ネストを削除し、完全版へのポインタとしてremnawave_describe_operationを指します。脱出ハッチ(2 ツール)。 仕様が欠落しているものに対する生の GET と生の書き込み。
すべてのルートは同じ実行エンジンを通過するため、書き込みゲート、破壊的確認ゲート、パステンプレート、クエリ処理は、どのサーフェスを使用しても同じように動作します。
好みに応じてプロファイルを選択してください: 多くの MCP サーバーを接続している場合は minimal、日常的なオペレーションを 1 コールで呼び出したい場合は core、コンテキストが問題にならない場合は full。
フィールドノート — 仕様が文書化していない動作
これらはすべてライブの 3.3.2 パネルに対して確認され、影響を受けるオペレーションのツール説明に添付されています。
PATCH /api/config-profilesはパッチではなく置換です。 ボディは{uuid, config}で、configは完全で有効な Xray 設定でなければなりません。断片はA061: Config doesn't have inboundsで失敗します。正しい手順:GET /api/config-profiles/{uuid}→ 返されたconfigオブジェクトをその場で編集 → 全体をPATCHで戻す。パネルは
127.0.0.1:3000では応答しません。 パネルホスト自体からでも、docker-proxyがそこで待ち受けていても(curlは exit 52、空の応答を返します)。常に Bearer トークン付きの公開 HTTPS オリジンを使用してください。すべての応答は
{"response": ...}でラップされています。 このサーバーはそれをアンラップするため、ツール出力はペイロード自体になります。ホストはネストされた
inbound.configProfileUuid(およびinbound.configProfileInboundUuid)を介してプロファイルにバインドされます。 トップレベルのconfigProfileUuidではありません。ライブホストで確認済み: ネストは存在し、トップレベルは存在しません。一連の
PATCHはパネルをダウンさせます。 各設定書き込みはすべてのノードにプッシュし、そこで Xray を再起動します。数回続けると、パネル自身の TLS リスナーが応答しなくなります。クライアントは変更を直列化し(REMNAWAVE_WRITE_MIN_INTERVAL_MS、デフォルト 1500 ms)、トランスポート障害を指数バックオフとジッターで再試行します。並列で一括更新を発火してこれを無効にしないでください。POST /api/subscription-templatesは空のテンプレートのみを作成します。 コンテンツは別のPATCH /api/subscription-templatesでアップロードされます。JSON と YAML のボディを同じ呼び出しで更新することはできません。ホストの
serverDescriptionは 30 文字に制限されています(仕様のmaxLengthで確認済み)。また、Hysteria2 ホストを生の JSON ではなく Happ で正しくレンダリングするための要素でもあります。16 のエンドポイントは管理者 JWT 専用です —
authとpasskeysコントローラ全体、および API トークン管理(GET/POST /api/tokens、DELETE /api/tokens/{uuid}、GET /api/tokens/scopes)。パネルはそこでの API トークンに 401/403 で応答します。このサーバーは仕様からそれらを検出し、ローカルで拒否します。REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1は、設定したトークンが実際に管理者 JWT である場合にゲートを解除します。GET /api/users/streamは改行区切り JSON で応答します、1 つのドキュメントではありません。テキストの塊として返すのではなく、ユーザーレコードの配列に解析されます。PATCH /api/hostsは実際の部分パッチです —{uuid, serverDescription}だけで機能します。設定プロファイルだけが全体置換のセマンティクスを持ちます。ライブで確認済み。エラーは
{message, errorCode}として返されます。errorCode(例:A061)はこのサーバーのエラーテキストに含まれます。
ツールカバレッジ
すべてのコントローラは remnawave_call と脱出ハッチから到達可能です。型付き列は、REMNAWAVE_TOOL_PROFILE=core の下で個別のツールを取得するものを示しています。
Controller slug | 操作数 |
|
| 17 | はい |
| 18 | — |
| 15 | はい |
| 12 | — |
| 12 | はい |
| 12 | はい |
| 10 | はい |
| 9 | はい |
| 8 | — |
| 7 | — |
| 7 | — |
| 7 | — |
| 7 | はい |
| 7 | — |
| 7 | — |
| 7 | — |
| 6 | — |
| 5 | — |
| 5 | — |
| 5 | — |
| 4 | — |
| 4 | はい |
| 4 | — |
| 3 | — |
| 2 | — |
| 2 | — |
| 2 | — |
| 1 | — |
合計 | 205 |
正確で最新の一覧については、稼働中のサーバーに対して remnawave_list_operations を実行してください。
例
型付けされたツールを使わずに閲覧・呼び出しを行う場合:
// 1. What is there?
{ "tool": "remnawave_list_operations", "arguments": { "controller": "nodes" } }
// 2. What does it take?
{ "tool": "remnawave_describe_operation",
"arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart" } }
// 3. Do it.
{ "tool": "remnawave_call",
"arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart",
"params": { "uuid": "…" } } }params、body、query は JSON テキストとして届くこともあります — "params": "{\"uuid\":\"…\"}" —
これは、一部の MCP クライアントが型付けされていないツール引数をパースせずにそのまま転送するためです。
文字列は自動的にパースされます。JSON でない文字列は、その旨を伝えるメッセージとともに拒否されます。
設定プロファイルを安全に編集する(A061 の罠):
// Read the whole profile first — PATCH replaces the config wholesale.
{ "tool": "remnawave_call",
"arguments": { "operation": "remnawave_get_config_profiles_uuid", "params": { "uuid": "…" } } }
// Send the full, edited config back.
{ "tool": "remnawave_call",
"arguments": { "operation": "remnawave_patch_config_profiles",
"params": { "body": { "uuid": "…", "config": { /* complete Xray config */ } } } } }仕様では表現できないクエリ構文:
{ "tool": "remnawave_request_read",
"arguments": { "path": "/api/users",
"query": { "size": 25, "start": 0,
"filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }テスト
npm run build
npm test # 50 unit tests + the offline smoke suite
npm run test:unit # unit tests alone単体テストは、静かに失敗する部分をカバーしています: Remnawave の再帰的 DTO を通じた $ref 展開、ツール名の導出(長さの予算、決定性、衝突検出)、カタログの差分、両方の書き込みゲート、admin-JWT ゲート、スキーマの圧縮、NDJSON のパースです。
実パネルに対する読み取り専用チェック
パネルに到達可能で、環境に読み取りトークンがある場合、スモークスクリプトはライブの読み取り専用呼び出しも実行します(変更は一切行いません):
REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smokeトークンがすでに存在する場所(例: パネルホスト上)で実行してください。シークレットが外部に漏れないようにするためです。スクリプトは型、キー名、配列の長さといった形状のみを出力し、ペイロードの値は決して出力しないため、その出力は issue に貼り付けても安全です。
ガードレールチェックは意図的に http://127.0.0.1:9 を指しています。ゲートが万一オープンに失敗しても、実際のパネルには到達できないようになっています。
書き込みパスの検証
読み取りだけでは、トークンのルーティング、スロットル、確認ゲート、部分パッチのセマンティクスが実際に機能することを証明できません。scripts/write-check.mjs は、誰もアタッチしていないオブジェクトに対してそれらを証明し、触れた既存オブジェクトを 1 つ元に戻します:
REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$T" REMNAWAVE_API_TOKEN_WRITE="$T" \
node scripts/write-check.mjs --i-understand-this-mutates [--host-uuid <uuid>]インバウンドもメンバーも持たない内部スクワッドを作成して再度削除し、次に 1 台のホストの serverDescription を書き換えて元の値に復元します。確認フラグなしでは起動を拒否し、何かが残っている場合は非ゼロの終了コードを報告します。
実稼働中の 3.3.2 パネルに対して、以下が確認されました: 確認ゲートが実際の DELETE で機能すること、部分的な PATCH /api/hosts が機能すること、パネルが 31 文字の serverDescription を拒否すること、元の値(null を含む)が往復すること、そして連続する変更が設定された 1500 ms の下限に対して 1525 ms と 1524 ms の間隔で実行されたこと。
ローカルでの確認
REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspectAPI 仕様の更新
API に関するすべては 1 つのファイルから来ているため、新しい Remnawave リリースへの追従は 1 つのコマンドで完了します:
npm run update-spec # fetch the newest spec + rebuild the catalogue
npm run update-spec -- --strict # additionally fail if any operation disappeared or was renamed
npm run build && npm test # compile and verify仕様の入手元
https://cdn.remna.st/docs/openapi.json — Remnawave 自身の Build&Push OpenAPI Specs ワークフローがすべてのアップストリームタグで公開しているもので、常に最新リリースを記述しています。--url <u> または REMNAWAVE_SPEC_URL で別のソースを指定して上書きできます。
パネルインスタンスは有効なソースではありません: ドキュメントはデプロイメントが有効にしない限り無効化されており、有効にしても Swagger は /backend-tools/swagger にマウントされ、通常のリバースプロキシはそこをルーティングしません。実稼働中の 3.3.2 パネルを調べたところ、従来の仕様パスすべてで 404 が返されました。
ダウンロードは、非空の paths を持つ OpenAPI ドキュメントとしてパースできた場合にのみディスクに書き込まれるため、エラーページやキャプティブポータルが正常な仕様を上書きすることはありません。
その後の確認事項
build-spec は新しいカタログを以前のものと差分比較し、すべての変更を出力します:
build-spec: Remnawave API v3.4.0 -> 211 operations, 28 controllers, 315 KB
methods: DELETE=22 GET=90 PATCH=19 POST=78 PUT=2 admin-JWT-only: 16
diff: API version 3.3.2 -> 3.4.0
REMOVED — tools that will disappear (1):
remnawave_get_old_thing (GET /api/old-thing)
added (7):
...REMOVED / RENAMED は、それらのツールを名前で参照するプロンプトやスクリプトを持つ人にとって破壊的変更です。
--strictはそれらを非ゼロの終了コードに変換します。これは自動化が使用すべきフラグです。added は安全です。新しい操作は
remnawave_callを通じて即座に利用可能になり、そのコントローラーがアクティブなプロファイルにある場合は型付けされたツールも取得されます。schema changed は、実際に使用する操作について一瞥する価値があります。
npm test はその後、ディスク上のカタログが新規ビルドと一致すること、すべてのツール名が一意で 64 文字の予算内にあること、ガードレールが引き続き機能することを再確認します。
自動化
npm run update-spec -- --strict # exits non-zero on a breaking catalogue change
npm test
npm version minor --no-git-tag-version
git commit -am "chore: Remnawave API 3.4.0" && git push
git tag "v$(node -p "require('./package.json').version")" && git push --tagsプッシュされたタグはリリースワークフローをトリガーし、npm への再公開を行います。@folexz/remnawave-mcp@latest で登録されたクライアントは、次回起動時に新しいバージョンを取得します。
リリース(メンテナー向け)
初回公開 — 必然的に手動
npm はまだ存在しないパッケージに対して信頼できるパブリッシャーを設定できません。その設定はパッケージ自身の設定ページに存在するためです。これは既知の、まだ未解決の制限です(npm/cli#8544)。スコープ付きパッケージにも適用されます。したがって、バージョン 0.1.0 はログイン済みのマシンから公開する必要があります:
npm whoami # must print the account that owns the @folexz scope
npm publish --access public--access public は必須です。スコープ付きパッケージはデフォルトで restricted になるためです。
その後、トークンレスリリースに切り替え
パッケージが存在すれば、npmjs.com → @folexz/remnawave-mcp → Settings → Trusted Publisher で、リポジトリ folexz/remnawave-mcp、ワークフロー release.yml の GitHub Actions パブリッシャーを追加します。package.json の repository.url は GitHub リポジトリと正確に一致している必要があります — 一致しています。
その後、.github/workflows/release.yml は、プッシュされた任意の vX.Y.Z タグで OIDC 経由で公開します — トークンもシークレットも不要で、provenance が自動的に付与されます:
npm version patch --no-git-tag-version
git commit -am "chore: v0.1.1"
git push
git tag v0.1.1 && git push origin v0.1.1ワークフローはロックファイルから再インストールし、再ビルドし、単体テストとオフラインスモークスイートを実行し、タグが package.json と一致しない場合は即座に失敗します。
@folexz/remnawave-mcp@latest で登録されたクライアントは、次回起動時に新しいバージョンを取得します。
セキュリティに関する注意
トークンは環境からのみ読み取られ、決してログに記録されません。ログは stderr に出力されます。stdout は MCP JSON-RPC チャネルです。
REMNAWAVE_API_TOKEN_READのみを設定することを推奨します。書き込みトークンがなければ変更ツールは存在しないため、侵害されたクライアントや混乱したクライアントがパネルを変更することはできません。サブスクリプションエンドポイントは動作するクライアント設定を返します。その出力は機密として扱ってください。
実際のトークンをコミットしないでください。
.envは gitignore されています。.env.exampleが形状を示しています。
既知の制限
ボディ検証はパネルに委任されています。 このサーバーは必須引数と必須の
bodyが存在することのみをチェックし、ボディの内部構造をスキーマに対して検証しません。これは意図的です — パネルはすでにすべてのフィールドを検証し、正確なmessage+errorCode(例:A061)で応答します。それをローカルで複製するには、JSON Schema バリデーターと、必然的に乖離するルールの 2 番目のコピーを同梱する必要があります。コストは、不正なボディが判明するまでに 1 往復かかることです。エスケープハッチは操作ごとのゲートをバイパスします。
remnawave_request_writeは設計上 raw です。書き込みトークンは依然として必要で、スロットルとリトライロジックも通過しますが、破壊的なconfirmゲートや admin-JWT チェックは適用されません。これは、それらを参照する操作がないためです。仕様に記述されていないルートが必要でない限り、remnawave_callを優先してください。ツールは同梱された仕様(v3.3.2)と同じだけ最新です。 異なるマイナーバージョンのパネルは、仕様に記述されていないルートを公開している可能性があります。それがエスケープハッチの目的です。API 仕様の更新 を参照してください。
admin-JWT エンドポイントはゲートされており、実装されていません。 このサーバーは API トークンを保持します。管理者ログインの実行、セッションの保持、JWT の更新は行いません。管理者 JWT をトークンとして提供し、
REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1を設定すると、それらの 16 エンドポイントが呼び出し可能になりますが、有効期限と更新は自己責任です。Prometheus の basic-auth メトリクスエンドポイント はこの仕様の一部ではなく、公開されていません。
write-check.mjsは変更を行います。 これはメンテナー向けツールであり、npm testから除外され、明示的な確認フラグなしでは実行を拒否します。
ライセンス
MIT — LICENSE を参照してください。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
EU cloud as MCP tools: VPS, databases, caches, storage, containers and more. Takes an API token.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Related MCP Servers
- AlicenseCqualityBmaintenanceWraps the Remnawave API to provide per-operation MCP tools with mutation safety and data redaction, enabling secure interaction with Remnawave panel.100MIT
- AlicenseCqualityBmaintenanceEnables MCP clients like Claude Code, Claude Desktop, or Cursor to read and manage Remnawave 3.x VPN panel resources — users, nodes, hosts, config profiles, squads, subscription templates, billing, and HWID devices — through the panel's REST API, with contract-driven tool schemas, numeric user IDs, multi-panel config lookup, and an optional readonly mode.20413 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables managing and observing Technitium DNS Server through MCP, including read-only or read-write tool surfaces, scoped bearer authentication, audit logging, and confirmation gates for destructive operations.MIT
- AlicenseCqualityCmaintenanceEnables managing a Remnawave VPN panel from MCP clients, providing tools for users, nodes, subscriptions, statistics, billing, and system operations, plus resources and prompts for common admin tasks.19013 npmMIT