remnawave-mcp

[(https://www.npmjs.com/package/@folexz/remnawave-mcp) [(https://github.com/folexz/remnawave-mcp/actions/workflows/ci.ym) [(./LICENSE) [(https://nodejs.org)

Remnawave パネル API 用の [MCP]（https://modelcontextprotocol.io）サーバーです。

@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 件の操作 — users、nodes、hosts、config profiles、squads、subscriptions、node plugins、infra billing、system stats — をカバーしています。手書きではしく、パネルの自己の OpenAPI ドキュメントから生成かれています。新しい spec を npm run build-spec に渡すとなくもツール面も追従します。

特

• 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 のエンドポイント (auth、passkeys、API トークン管理) は、ログイン済みの管理 JWT にのみ応答し、API トークンははねます。これらは spec から検出され、送信されずに、説明とともにローカルで拒否されます。

• エスケープ・ハッチ — remnawave_request_read / remnawave_request_write は、ドキュメント化される前のルートや OpenAPI が表現できないクエリ構文も含む任意のパスに届きます。

必要条件

• Node.js ≥ 18

• HTTPS で到達できる Remnawave パネル (3.x)

• パネルから発行された API トークン: Settings → API tokens。Remnawave 3.x はスコープ付きトークンに対応しています。読み取りスコープのトークンと、変更トも行うるな２つ目の書き込みスコープのトークンを発行してください。

インストール

npx が一番ですか — [Claude Code に登録する]（#register-with-claude-code）を参照してください。ソースから実行する場合:

git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build

設定

設定のすべては、MCP ホストが供給する環境変数を。ファイルの読込はありません。

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/indx.js に置き換えてください。

Claude Desktop / other MCP clients に登録

{
  "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 は全 requests モデルに再送されるため、その serialize さされたサイズは恒久のコンテスト税です。この spec で測った数値 (npx tsx scripts/tool-stats.ts):

Remnawave の DTO が full をこれだけ高くする理由です: 参照を解決し終えた host オブジェクト1 つだけで JSON Schema 約 30 KB あり、その理由は、インバウンドとセキュリティのすべてのバリアントを埋め込むこのから。

そこでこのサーバーは「操作あ当たり 1 ツール」と「大ざっくりなディスパッチヤー」のどちらかを選ぶのではなく、両方を①提供し、どの程度公開するのかをプロファイルに委ねます。

1. カタログ・ツール (常に有効、3 ツール) — remnawave_list_operation lisいてカタログを閲覧・検索し、操作ごと1 行を返しますします。remnawave_describe_operation は操作 1 つの完全な JSON Schemaとフィールドノートを返します。remnawave_call は 205 のどれかを指定して実行します。通常のループは list → describe → call で、API 大きくなってもコストが同ーの約 1.4k トークンです。これはエージェトがツールスキーマを遅延読込ときと同じ lazy-loading の考え方です。

2. 型付きツール (プロファイルによ選択) — 実際に触るコントローラの操作ごとに生成されたツールです。core は users、nodes、hosts、squads、internal squads、system、および 2 つの bulk-action コントローラーをカバーします。full は全体を、minimal は何もカバーしません。REMNAWAVE_MAX_SCHEMA_BYTES を超するスキーマはトップレベルのフィールドだはで保ち、ネストを落とし、完全版のアドレスとして remnawave_describe_operation を差し示すします。

3. **エスケープ・ハッチ (2 ツール) ** — 仕様が落してる何れかに対する raw の GET と raw 書込み。

すべてのルートは同じエグゼキューターを通るため、書き込みゲート、破壊的確認ゲート、パステンプレート、クエリ処置はどこの面ても同義に動きします。

プロファイルは好みで選んでください。っのMCPサーバーが多接続してるなら minimal、日常のの操作を 1 呼びで宣言したいは core、コンテストを気にしなければ full。

フィールド・ノート — spec が文書化してい ない挙動

これらはすべて、このライブ 3.3.2 パで当ったもので、影響操作のツール説明に付属しています。

• PATCH /api/config-profiles は置換である。patch ではない。 body は {uuid, config} であり、config は 完全有効な Xray設定でなけれ。部品の一部 Fragmment は A061: Config' doesn't have inbounds で失敗ます。正しい流れ: GET /api/config-profiles/{uuid} → 帰ってきた config オブジェクトを現地編集する → その全体を PATCH で書き戻す。

• パネルは 127.0.0.1:3000 には応答しない — パネル自身のホストから、て dock ー proxy がそこ待受けていても。curl は開催 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 と YAMAL body を同じコールで更新するできない。

• ホストの serverDescription は 30 文字まで最大 (spec の maxLength で確認)。またこれを Happ で Hysteria2 ホを受けるの適切な表示(ホそこと)。

• 16 のエンドポイントは admin-JWT 専用 — auth と passkey の全コントローラのほ、API-トークンの認管 (GET/POST /api/tokens, DELETE /api/tokens および GET /api/tokens/scopes)。パネルはこのAPI・トークンに対し401/403を返します。こサーバーは仕様からこれらを検知し、ローカルで拒否します。REMNAWOAVE_ALLOW_ADMIN_JWT_OPS=1 を設定して、よ **トークンが、できなるアで本当 admin の JWT のがの場化のみ) そのゲートを上げします。

• GET /api/users/stream はニューライン区切リ JSON を返します**..支えずに。ユーザーのレコードの配列としてパースされるです。

• PATCH /api/hosts は本当に部分パッチ — {uuid, serverDescription} だけで動ها。Only the whole config profiles have the replace everything semantics. 実機確認済み。

• Error は {message, errorCode} として返ります。このサーハーのエラー文には errorCode (例: A061) が含まれれて。

ツールカバーシ

すべてのコントローラーは remnawave_call との2つのエスケープ・ハッチから到来できます。**型付きコント理論なら、REMNAWAVE_TOOL_PROFILE=core で個別のツールが作られはどこかを示しています。

正確な現在の一覧については、ライブーで remnawave_list_operopes を実行してください。

Examples

型付きツールなしで閲覧して呼び出す:

// 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": "…" } } }

（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 */ } } } } }

API 仕様では表現できないクエリ構文:

{ "tool": "remnawave_request_read",
  "arguments": { "path": "/api/users",
                 "query": { "size": 25, "start": 0,
                            "filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }

Testing

npm run build
npm test            # 50 unit tests + the offline smoke suite
npm run test:unit   # unit tests alone

ユニットテストは、妨害なく失敗する部分をカバーしています。つまり、Remnawave の再帰的な DTO を貫く $ref の展開、ツール名の生成（長さの予算・決定性・衝突検出）、カタログの差分、両方の write ласьド、管理-JWT のート、スキーマの短路、NDJSON の解析です。

実体のエーントに対する読み取り専用

パネルに到達可能で、環境に read トークンがある場合、スモークスクリプートは読み取り専用のライブ呼び出しも実行します（変更は決して行いません）:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smoke

トークンが既に置いある場所（例ぱパネルのホスト上）で実行してください。これで、シクレットが移動することはありません。スクリプートは形（型、キー名、配列の長さ）だけを出力し、ペイロード値は出力しません。そのため、その出力量はイシューに貼り付けても安全です。

ガードルールのチェックは 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 を書き直し、元の値に戻します。ま-ta、明示フラッグが指定されていなければ開始を拒否し、何か残っいれば非ゼロの終了コードを返します。

ライブ 3.3.2 のパネルとの確認内容は以下です。確認ゲートは実際の DELETE で保たれ;部分的な PATCH /api/hs が機能;パネルは 31 文字のAPSK serverDescription を拒否;元の値（null を含む）が丸く戻る;連続した変更の間隔は、設っい 1500 ms の下限に対して1525 ms と1524 ms と間隔が空いている。

ローカルで確認する

REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspect

API仕様の更新

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 ワークフローで配置したものです。各アップストリームのタグごとに公開され、常に最新のリリースを記述っています。別の元を固定したい場合は --url <u> または REMNAWAVE_SPEC_URL で上書きできます。

パネルのインスタンスは 利用可能なソースではありません。ドキュメントはデプロイメントが明示的に有効にする場合を除いて無効になっており、しかも Swagger は /backend-tools/swagger にマウントされますが、通常はリバースププロキではルーテイングされません。ライブ 3.3.2 のパネルを調査したとこ、従来の spec パスはもんなル 404 でした。

ダウンロードは、空でない paths を持った OpenAPI ドキュメントとして解所できた場合に限りディスクに書込みます。だからエラページやキャプテブポータルが正常な spec を壊しません。

その後の確認内容

bullet-spec は、新カタログを前回りのカタログと diff し、すべての変更をプリントします。

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 は安全です。新しオペレーションには remode_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 は、OID 経由で PUSH された vX.Y.Z タグに対して公開します。トークンもシークレットも不, 要で、出所の証明 (proveance) が自動付与されます:

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/rermnawave-mcp@latest を登録しているクライアンは、次回の起動に新バージョンを提出します。

Security notes

• トークンは環境変数のみから読み込まれ、決してログ記録しません。ログは stderr に出し、stdout は MCP JSON-RPC チャンネルです。

• 構成は REMNAWAVE_API_トークン_READ だけに限推奨します。書き取りトークンがないと変更系ツール存まりないため、危険あるいは混乱にクライアントが変更できませ。

• サブスクレーションの point は動作するクライアント設定を返します。その出力量はシークレットと見なし。

• 実際のトークンをコミットしないでください。.env は gitignore、.env.example が形を implies。

既知の制限

• ボディの検証はパネルに委ねられてま。 このサーバー は必須引数と必須の body が存在ることをチェックまスが、・ボディの内側の形を schema に対して検査Innerしません。これは意図的です。パネルは既に全て

のフィールドを検証し、正確な message と error（たとえば A061）で応えるからです。それをローカルで複製するには JSON Schema の 検証器と、必ずずずれる2つ目の規則コピーを配布ることになります。その代わりは、不正なボディは一往復分のコストです。

• エスケープハートチは操作ごとのゲートを bypass しません。``remnawave_request_writeはわざと的 raw です。y? Still requires write token and goes through throttle and retry, but does not apply destructiveconfirmgate or admin-JWT check, because it has no operation to look those from. Preferremnawave_call`.

• MCPツールは郵送された spec と同じ ver の新しさです (v3.2). パネルが別のマイナー版で実装されたるroutes があるれば, spec is not described; that is what escape hatches for.

• Admin-JWT endpoints are gated, not implemented. This server carries API tokens; it does not perform admin login, hold or session, refresh JWT. If you provide Admin-JWT as token and set REMWAVE_ALLOW_ADMIN_JWT_OPS=1, those 16 使えますが、expired二延長は自分の責任です。

• Prometheus basic-auth metrics 用の point はこの spec の対象外で、露出していません。

• write-check.mjs は変更を加える。 メインテナー用ツールであり、npm test には含まれず、明示的な ack flag が冚けなければ起動しません。

ライセンス

MIT — LICENSE を参照してください。