TP-Link Easy Smart Switch MCP

TP-Link および Mercury Easy Smart スイッチ向けの TypeScript + Bun MCP サーバー。スイッチの Web UI を通じて動作し、SNMP には依存しません。

デフォルトターゲット: http://192.168.3.10

Codex プラグインとしてインストール

まず Bun をインストールし、次に独立した network-tools マーケットプレイスとこのプラグインを追加します:

codex plugin marketplace add qwe7002-ai/net-tool-plugins --ref main
codex plugin add tplink-easy-smart-switch-mcp@net-tool-plugins

インストール後、新しい Codex タスクを開始して、MCP ツールとスイッチ管理スキルが読み込まれるようにしてください。

Related MCP server: mcp-omada

テスト済みモデル

現在の実装は、以下の Web UI スナップショットと読み取り専用ステータス呼び出しに対してテストされています:

• TP-Link TL-SE2106（192.168.3.10）、ファームウェア 1.8.1 Build 20251128 Rel.57341

• Mercury SE106 Pro（192.168.3.11）、ファームウェア 1.0.0 Build 20240812 Rel.65021

他の TP-Link または Mercury Easy Smart スイッチでも、同じ Web UI ページと CGI エンドポイントを使用していれば動作する可能性がありますが、まだ検証されていません。

確認済みデバイスの特性

• 管理 UI は HTTP 80 で利用可能です

• ログインフォームは POST /logon.cgi に送信します

• ログインフィールドは username と暗号化された password です

• ログインページは /cryp_new.js を読み込みます

• 既知の Web UI 変数には、g_product、g_year、encryptType が含まれます

• 一部のファームウェアでは、リクエストトークンが引用符で囲まれた文字列ではなく、g_tid=1320064778; のようなベア数値代入として公開されます。他のページでは top.g_tid のみを参照する場合があるため、パーサーは代入と参照を区別する必要があります。

ツール

読み取り専用ツール:

• get_switch_status: スイッチステータスの概要を返します

• get_port_status: ポートステータスを返します

• get_vlan_status: ポート VLAN、802.1Q VLAN、PVID、MTU VLAN のステータスを返します

• get_trunk_status: ポートトランキング/LAG ステータスを返します

• search_mac_address: 1 つの MAC アドレスを mac_address_search.cgi に照会し、スイッチにエントリがある場合に学習したポート/VLAN を返します

• analyze_topology: 2 台以上のカスケード接続されたスイッチを分析し、スイッチ間リンクポート、アップストリーム/ダウンストリームの関係、およびリンクを跨ぐ VLAN の関係を報告します

トポロジ分析は、各スイッチにログインし、MAC 検索 CGI にピアスイッチの管理 MAC を問い合わせることで動作します。スイッチがピア MAC をポート上で報告した場合、そのポートはスイッチ間リンクの証拠として使用されます。MAC 検索でリンクを確認できない場合、検出はアクティブな SFP/10G ポートペアを低信頼度の推測としてフォールバックし、VLAN の重複を優先し、ライブトラフィックをタイブレーカーとして使用します。これらの Easy Smart スイッチには LLDP がないため、このインバンド相関が利用可能なシグナルです。

設定 CGI ツール:

• configure_mtu_vlan: VlanMtuRpm.htm から mtuVlanSet.cgi を生成または送信します

• configure_port_vlan: VlanPortBasicRpm.htm から pvlanSet.cgi を生成または送信します

• configure_8021q_vlan: Vlan8021QRpm.htm から qvlanSet.cgi を生成または送信します

• configure_vlan_pvid: Vlan8021QPvidRpm.htm から vlanPvidSet.cgi を生成または送信します

• configure_trunk_group: PortTrunkRpm.htm から port_trunk_set.cgi / port_trunk_display.cgi を生成または送信します

• save_configuration: SavingConfigRpm.htm から POST savingconfig.cgi を生成または送信します

設定ツールはデフォルトで apply: false となり、ドライランリクエストのプレビューを返し、何も送信しません。実際の書き込みには、以下のすべてが必要です:

• apply: true

• confirm: "APPLY"

• ログインの成功

• Web UI のルール検証に合格

• 読み取り可能な token/top.g_tid

インストール

bun install

開発中の実行

bun run src/index.ts

バイナリのビルド

Windows:

bun run build:win

現在のプラットフォーム:

bun run build

ビルド出力は dist/ に書き込まれます。

MCP クライアントが initialize 中に古いサーバーバージョンを報告する場合、その command はおそらく古い実行可能ファイルを指しています。それを dist/tplink-easy-smart-switch-mcp.exe に更新し、クライアントを再起動してください。

MCP のデバッグ

MCP ツールを一覧表示:

bun run debug

スイッチステータスツールを呼び出し:

bun run debug -- --tool get_switch_status --host 192.168.3.10 --username admin --password your-password
bun run debug -- --tool get_switch_status --host 192.168.3.11

ポートステータスツールを呼び出し:

bun run debug -- --tool get_port_status --host 192.168.3.10 --username admin --password your-password

送信せずに設定リクエストをプレビュー:

bun run debug -- --tool configure_mtu_vlan --params '{ "enabled": true }'
bun run debug -- --tool configure_port_vlan --params '{ "mode": "set", "vid": 1, "ports": "1,2" }'
bun run debug -- --tool configure_8021q_vlan --params '{ "mode": "set", "vid": 20, "name": "main", "untaggedPorts": "3", "taggedPorts": "5,6" }'
bun run debug -- --tool configure_vlan_pvid --params '{ "pvid": 20, "ports": "3" }'
bun run debug -- --tool configure_trunk_group --params '{ "mode": "set", "group": 1, "ports": "1,2" }'
bun run debug -- --tool save_configuration --params '{}'

ページサンプル

読み取り専用の開発スナップショットは以下の場所に保存されています:

• examples/tplink-192.168.3.10: 192.168.3.10 の TP-Link Easy Smart スイッチ

• examples/mercury-192.168.3.11: 192.168.3.11 の Mercury SE106 Pro

これらには、VLAN、トランキング、設定のバックアップ/リストア、設定保存ページに加えて、pvlan.js、qvlan.js、menuList.js が含まれています。これらのサンプルには SessionID 値やパスワードは含まれていません。

生の JSON-RPC を送信することもできます:

bun run debug -- --raw '{ "jsonrpc": "2.0", "id": 99, "method": "tools/list", "params": {} }'

MCP クライアントの例

{
  "mcpServers": {
    "tplink-easy-smart-switch": {
      "command": "C:\\path\\to\\tplink-easy-smart-switch-mcp.exe",
      "env": {
        "TPLINK_HOST": "192.168.3.10",
        "TPLINK_USERNAME": "admin",
        "TPLINK_PASSWORD": "your-password"
      }
    }
  }
}

注記

ページコンテンツは DOM パーサーで解析され、タイトル、フォーム、フレーム、リンク、テーブル、テキストの要約に正規化されます。ステータスデータは主に MainRpm.htm、VlanPortBasicRpm.htm、Vlan8021QRpm.htm、Vlan8021QPvidRpm.htm、VlanMtuRpm.htm、PortTrunkRpm.htm などのページ内の JavaScript 変数から抽出されます。

テスト済みの TP-Link TL-SE2106 および Mercury SE106 Pro ファームウェアでは、MacSearchRpm.htm は完全なフォワーディングテーブルのダンプではなく検索フォームです。したがって、サポートされている MAC 機能は search_mac_address であり、ページロジックに従って mac_address_search.cgi を txt_macAddress_search、txt_vid_search、token とともに呼び出します。

トークン抽出は、引用符付き g_tid、ベア数値 g_tid、および非表示の token 入力をサポートします。キャプチャスクリプトは、開発サンプルを保存する前に、引用符付きとベアの両方の g_tid 代入をマスクします。

設定 CGI 呼び出しは、明示的な確認フローを使用します。開発とデバッグはデフォルトでドライランになります。save_configuration も書き込みアクションです。SavingConfigRpm.htm のページロジックに従い、POST savingconfig.cgi を使用しますが、明示的に確認されない限り送信しません。