keenetic-mcp

keenetic-mcp

Claude、Codex、Cursor、または任意の MCP エージェントから Keenetic ルーターを操作できます。

エージェントに自然な言葉でネットワークについて尋ねてください。USB メモリも Entware も不要で、 ルーターには何もインストールされません。

> who is using the most bandwidth right now?

  Three devices are active. Sorted by traffic:

  work-laptop      wifi:HomeNet   -46 dBm    7.7 GB down
  living-room-tv   wired:Home                3.2 GB down
  hallway-camera   wifi:HomeNet   -48 dBm    5.4 MB down

  The laptop is on the 2.4 GHz radio at -46 dBm, which is a strong
  signal, so the throughput is not a coverage problem.

> block the camera until tomorrow morning

  Blocked hallway-camera (02:00:00:00:00:14).

  Applied to the running configuration and verified, but NOT saved.
  A reboot discards it. Backup taken before the change:
  ~/Library/Application Support/keenetic-mcp/backups/…txt

  Say the word and I will make it permanent, or leave it and it
  reverts on the next restart.

なぜ

• ルーター上に何も置きません。 LAN 経由でルーター自身の HTTP API と通信します。USB ドライブも Entware もファームウェアの改変も不要です。
• あらゆる Keenetic で動作します。 ツールセットは、お使いの特定のモデルとファームウェアが実際にサポートする内容に適応します。
• 構造的に安全です。 変更はあなたが要求しない限り保存されず、最初の変更の前にバックアップが取得され、すべての変更は完了として報告される前に読み戻して検証されます。
• 望めば読み取り専用にできます。 1 つのフラグで、エージェントは物理的に何も変更できなくなります。

インストール

Claude Code

/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keenetic

次に、ターミナルでセットアップウィザードを実行します:

npx -y keenetic-mcp init

Codex

codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp init

これにより、サーバーとともにスキルも導入されます。サーバーのみの場合:

codex mcp add keenetic -- npx -y keenetic-mcp

その他

{
  "mcpServers": {
    "keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
  }
}

ウィザードはデフォルトゲートウェイからルーターを見つけ、それが本当に Keenetic であることを確認し、パスワードをルーターに対して検証し、パスワードをお使いのオペレーティングシステムのキーチェーンに保存します。設定ファイルに保存されるのはアドレスとログインのみです。

環境変数のほうが好みですか？ KEENETIC_HOST、KEENETIC_USER、KEENETIC_PASSWORD がすべてを上書きします。これはコンテナ内でこそ望ましい動作です。

できること

読み取り

ツール
list_devices	すべてのデバイス。アクティブ、有線、無線、ブロック済みで絞り込み、トラフィックまたは信号で並べ替え
get_device	1 つのデバイスの詳細: リース、Wi-Fi レート、ポリシー、スケジュール、トラフィック
list_interfaces	WAN リンク、ブリッジ、アクセスポイント、VPN トンネル
get_interface	1 つのインターフェースの詳細。WireGuard ピアを含む
get_wifi_status	バンドごとの無線、クライアント数付き
get_internet_status	到達可能性、およびどのチェックが失敗したか
list_routes	ルーティングテーブル、またはデフォルトルートのみ
list_policies	選択的ルーティング用の接続ポリシー
get_system_info	モデル、ファームウェア、CPU、メモリ、インストール済みコンポーネント
get_config_state	未保存の変更、誰がいつ何を変更したか
list_segments	すべてのブリッジ、および Web インターフェースがそれをセグメントとして表示するかどうか
backup_config	設定をローカルファイルにダウンロード

変更

ツール
update_device	名前変更、ブロックまたは許可、ルーティングポリシー・スケジュール・優先度の割り当て
set_interface_state	インターフェースを有効化または無効化
create_segment	Web インターフェースが実際に表示するゲストまたは IoT ネットワーク。Wi-Fi、DHCP、任意の VPN ルーティング付き
delete_segment	セグメントと、それとともに作成されたすべてを削除
save_config	保留中の変更を再起動後も保持

エスケープハッチ

ツール
rci_call	上記のツールでカバーされないもののために、任意のルーター API パスを呼び出し

含まれるスキル

このプラグインには 4 つのスキルが同梱されているため、エージェントは推測するのではなく、お使いのルーターがどのように動作するかを把握できます。1 つのプラグインディレクトリが Claude Code と Codex の両方に対応します。両者は異なるマニフェストを読み込みますが、同じスキルと同一のサーバー定義を共有します。

• keenetic-rci はルーターの API ツリーを教えます。どのパスが存在するか、どのパスが 100 KB を返すか、そしてルーター自身の設定からコマンドの正確な構文を復元する方法です。
• keenetic-safe-changes は変更のワークフローを教えます。ルーターのフェイルセーフが何を保護し、何を保護しないのか、そしてどのインターフェースが自分自身のアクセスを遮断するのかです。
• keenetic-segments は、ルーターが存在を認める分離ネットワークの構築を扱います。明白な方法で作ると、トラフィックは完璧に通すのに Web インターフェースには決して現れないゲストネットワークになります。それは、セグメントが VLAN に支えられており、その VLAN こそが誰もが省いてしまう部分だからです。
• keenetic-troubleshoot は、「インターネットがダウンした」「Wi-Fi の調子が悪い」「1 台のデバイスが接続できない」ための順序立てた診断プレイブックです。

安全性

• 頼まない限り何も保存されません。 変更は実行中の設定に適用され、save_config が呼ばれるまで再起動時に破棄されます。サーバーが自ら呼び出すことはありません。
• セッションの最初の変更前に自動でバックアップが取得されます。
• すべての変更が検証されます。 ルーターは一部の誤ったコマンドを黙って受け入れ、何も変更しません。そのため、各書き込みは読み戻して比較されてから、成功として報告されます。
• 読み取り専用モードは本当に読み取り専用です。 --read-only を指定すると、書き込みツールは登録されずに拒否するのではなく、そもそも登録されないため、エージェントはそれらを決して目にしません。
• パスワードはシステムキーチェーンに保存されます。設定ファイルには入らず、ログやツールの応答にも決して含まれません。
• LAN のみ。 クラウドも、テレメトリも、お使いのルーター以外への外部接続もありません。

各プラットフォームでパスワードがどこに保存されるか、そして問題を非公開で報告する方法は、SECURITY.md に記載されています。

対応ルーター

これが使用する API である RCI は、高価なモデルだけの機能ではなく KeeneticOS の標準的な一部であるため、幅広い機種で動作します。KeeneticOS 5.1.3 上の Keenetic Ultra (KN-1811) で検証済みです。

現在の 5.1 ブランチのモデル: Giga (KN-1010)、Hero (KN-1011、KN-1012)、Start および Starter (KN-1111、KN-1112、KN-1121)、Air および Explorer (KN-1613、KN-1621)、Extra および Carrier (KN-1713、KN-1714、KN-1721)、Ultra および Titan (KN-1810、KN-1811、KN-1812)。4.x 以前の古いハードウェアにも RCI はあります。ツールセットは、各ルーターが実際に持つコンポーネントに適応します。

仕組み

Keenetic ルーターは、コマンドラインツリーを JSON で映した RCI を HTTP 経由で公開します。このサーバーはルーターのチャレンジレスポンス方式で認証し、エージェントの問い合わせの間ずっと 1 つのセッションを維持し、モデルのコンテキストに収まるように応答を整形します。生のインターフェース一覧だけで 32 KB あり、NAT テーブルは 100 KB を超えます。

RCI に関する一貫した公開ドキュメントは存在しないため、docs/rci-api.md はこれを構築する間に取られたメモです。認証ハンドシェイク、存在するパス、落とし穴、そしてルーター自身からコマンドの構文を復元する方法を扱っています。

開発

npm install
npm test          # no router required
npm run typecheck
npm run build

チェックアウトしたコピーは、自身のバージョンを 0.0.0-dev として報告します。これは、ソース内のどこにもバージョンが書き留められていないためです。別のバージョンを指定したい場合は、リポジトリのルートにある .env に KEENETIC_MCP_VERSION を記述してください。同じファイルに KEENETIC_HOST と KEENETIC_PASSWORD を保持しておけば、それらをエクスポートする必要がありません。実際の環境変数は常にこのファイルより優先され、インストール済みのコピーはこのファイルを決して読み込みません。

テストは、実際のルーターから取得した匿名化済みのフィクスチャに対して実行されます。フィクスチャを更新するには、またご自身のルーターに対して読み取り専用のスモークテストを実行するには、次のようにします。

KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smoke

フィクスチャは決定論的に匿名化されており、実際の MAC アドレス、プライベート IP、鍵のように見えるものがリポジトリ全体に存在しないかをテストがスキャンします。

セットアップウィザードはターミナルからパスワードを読み取りますが、これはどのユニットテストからも到達できません。パイプされた入力はまったく別のコードパスをたどるためです。この部分は、実際の pty を操作するスクリプトで確認されるため、ターミナルが必要であり、CI では実行できません。

KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.exp

リリース

リリースはタグそのものであり、それ以外の何ものでもありません。リポジトリ内に変更すべきバージョンが存在しないため、書き込むべきバージョンコミットもありません。package.json は 0.0.0-dev を保持し、プラグインのマニフェストはバージョンをまったく保持しておらず、リリースワークフローは公開直前にタグを package.json に刻み込みますが、コミットはしません。

git tag v0.2.2 && git push origin v0.2.2

ワークフローはバージョンを示さないタグを拒否し、テストはバージョンが書き込まれたツリーを拒否するため、この 2 つが食い違うことは決してありません。プラグインは keenetic-mcp@^0 を固定しており、これはメジャーのみを追跡し、1.0 の時点で一度だけ編集されることを意図しています。

ライセンス

MIT