iptime-mcp

English | 한국어

iptime-mcp

Web 管理画面を何度も開かずに ipTIME ルーターを操作するための、安全確認付き Model Context Protocol（MCP）サーバーです。

ルーターの状態を調べ、特定のモデルとファームウェアがカタログに登録されたどの操作に対応しているかを確認し、ネットワーク、Wi-Fi、NAT、ファイアウォール、VPN、DDNS、USB/NAS、システム、自動化の機能に対する変更を確定して実行できます。

これは非公式のコミュニティプロジェクトであり、EFM Networks および ipTIME とは提携していません。ルーター API はファームウェアに依存し、安定した公開仕様として公開されていません。

主な機能

• トップレベルのツールを何百も用意する代わりに、用途を絞った MCP ツールを 13 個提供
• カタログに登録されたルーター操作を 334 件収録：読み取り 171 件、書き込み 163 件
• ルーターの api/has メソッドを使用して、iUX3 上で実行時に対応状況を確認
• iUX3、Mobile iUX、従来の CGI インターフェイスを検出
• 読み取り専用の操作は直接実行可能
• ルーターへの変更にはすべて、確認トークンを必要としない、短時間のみ有効でレビュー可能なプランを使用
• 設定のバックアップ、復元プランの作成、ファームウェアのアップグレード計画に対応
• 単一ルーターおよび複数ルーターのプロファイルに対応
• 認証情報とセッション値をマスキング
• パブリックな HTTP（暗号化なし）通信を既定でブロック

カタログには、管理、ファームウェア、バックアップと復元、WAN/LAN/DHCP/DNS、ルーティングとスイッチング、ワイヤレスと EasyMesh、NAT とポートフォワーディング、ファイアウォール、QoS、VPN、DDNS、USB/NAS サービス、ルーティン、履歴、ログ、ホストスキャン、Wake-on-LAN が含まれます。

互換性

インターフェース	サポート
iUX3	/cgi/service.cgi JSON RPC を使用し、既知の各メソッドを api/has で確認します
モバイル iUX	明示的にマッピングされた読み取り操作のみを公開します
Classic CGI	明示的にマッピングされた読み取り操作のみを公開します

固定操作カタログは、ファームウェア 15.36.6 に同梱された iUX3 アプリケーションで確認されたメソッドに基づいています。メソッドがカタログに掲載されていても、すべてのルーターでサポートされているとは限りません。操作を選ぶ前に、対象ルーターに対して必ず iptime_capabilities を使用してください。

ファームウェア 16.00.0 では、ipTIME ID、EasyMesh クライアント接続の固定、ページ分割されたシステムログが導入されました（公式リリースノート）。これらの追加機能は、このカタログに対して検証されていません。このサーバーは設定済みのルーターに直接接続します。ipTIME ID による認証や、クラウドリレーの提供は行いません。ファームウェアのバージョンやステータス照会の成功から、新機能がサポートされていると推測しないでください。ログについては、結果が完全なものと判断する前に、実際の応答とファームウェア固有のページ分割を確認してください。検証済みのメソッドのみを公開し、未知の書き込み機能は引き続きブロックされます。

ファームウェア 16.00.4 については、公式 A2004SE UI バンドルを調査しました。ACS CA 証明書は既存の cwmp/set メソッドを使用し、acs.cacert に PEM テキスト（最大 8192 バイト。"" を指定すると証明書を削除）を設定します。UI は active／acs／cpe の設定全体を送信します。そのため、証明書の変更には、実際の ACS／CPE 認証情報を含むこれらすべてのフィールドが必要です。不完全な設定や [redacted] のプレースホルダーは拒否されます。cwmp.get ではパスワードが隠されるため、そのままコピーして戻すことはできません。意図する設定全体を安全に指定できない場合は、変更を適用せずに中止してください。プランのリスクは引き続き重大で、読み戻しには cwmp/get を使用します。プライベート CA を使用する HTTPS ACS サーバーには、対応する証明書が必要です。検証を無効にしないでください。これはインターフェース契約の検証であり、すべてのモデルに対する実機ルーターの互換性認証ではありません。ipTIME ID／パスキーによるログインと新しい EasyMesh コントロールは、別途検証されるまでサポート対象外です。

共有設定メソッドには、iptime_read 経由で設定パラメーターを渡せません。これらのパラメーターは書き込みを実行する可能性があります。代わりに、変更プランを通じて対応する書き込み操作を使用してください。確認された ddns.config セレクター "iptime" は、読み取りでは引き続き許可されます。

レガシーサポートは、システム情報、DHCP リースと設定、ポート転送、Wake-on-LAN の既知の安全なマッピングに意図的に限定されています。レガシー応答は生テキストで返される場合があります。未知のレガシー書き込みは拒否されます。

安全性モデル

ルーターの変更によって、インターネット接続が中断したり、管理インターフェースにアクセスできなくなったりする可能性があります。そのため iptime-mcp では、読み取りと書き込みを分離しています。

1. iptime_plan_change またはファイル固有のプラン作成ツールは、ルーターを変更せずに不変のプランを作成します。
2. プランには、操作、パラメーター、取得可能な場合は現在の状態、リスク、有効期限が記載されます。
3. iptime_apply_change は plan_id のみを使用して、そのプランを正確に適用します。ユーザーが APPLY <UUID> トークンをコピーする必要はありません。

同じ変更を具体的に依頼していることは、十分な承認とみなされます。ファームウェア、復元、リセット、認証情報、ストレージ形式の操作など、重大なリスクを伴うプランが明示的に承認されていない場合に限り、クライアントは通常の言葉で再確認してください。MCP クライアントでは、通常の破壊的ツールに対する承認プロンプトが引き続き表示される場合があります。

プランの有効期限は 10 分で、1 回のみ使用できます。整合性ダイジェストが含まれ、ルーターごとに順次処理されます。書き込み応答が失われた場合、サーバーは読み戻しを試み、書き込みを自動的に再試行しません。プランはメモリ内に保持され、MCP プロセスの再起動時に消去されます。

要件

• Node.js 22 以降
• ルーターの管理用エンドポイントへのネットワークアクセス
• ipTIME の管理者ユーザー名とパスワード
• stdio サーバーに対応した MCP クライアント

可能な限り、LAN アドレス、VPN アドレス、または信頼できる HTTPS エンドポイントを使用してください。

npm からインストール

MCP クライアントの stdio コマンドとして npx -y iptime-mcp を指定し、プライベートな環境設定で IPTIME_ROUTER_URL、IPTIME_ROUTER_USERNAME、IPTIME_ROUTER_PASSWORD を設定してください。ルーターの URL は信頼できる LAN または VPN 上にしてください。以下の例では、ローカルのスクリプトパスを必要とするクライアント向けに、同等のソースからのインストール方法を示します。

ソースからインストール

git clone https://github.com/mikusnuz/iptime-mcp.git
cd iptime-mcp
npm ci
npm run build

実行可能なエントリーポイントは dist/server.js です。

環境ファイルまたは設定可能な作業ディレクトリに対応したクライアントの場合は、まずローカルに .env を作成してください。

cp .env.example .env

ルーターの URL、ユーザー名、パスワードを入力してください。.env は Git の対象外であり、ローカルに保管する必要があります。

MCP クライアントの設定

可能な限りユーザーレベルの設定を使用してください。ルーターの認証情報をプロジェクトにコミットすべきではないためです。各例の /absolute/path/to/iptime-mcp を置き換えてください。Windows では、C:/Users/name/iptime-mcp/dist/server.js のようなスラッシュ区切りのパスを JSON で使用できます。デスクトップクライアントが node を見つけられない場合は、macOS/Linux では which node、Windows では where node で表示される絶対パスを使用してください。

クライアント	ユーザーレベルの設定
Codex / ChatGPT デスクトップ	設定 → MCP サーバー または ~/.codex/config.toml
Claude Desktop	設定 → 開発者 → 設定を編集
Claude Code	claude mcp add --scope user
Cursor	~/.cursor/mcp.json
VS Code エージェントチャット	MCP: ユーザー設定を開く
GitHub Copilot CLI	~/.copilot/mcp-config.json
Gemini CLI	~/.gemini/settings.json

Codex / ChatGPT デスクトップ

設定 → MCP サーバーで stdio サーバーを追加するか、以下を ~/.codex/config.toml に追加してください。パスと認証情報を置き換えて保存し、MCP サーバーを再起動してください。

[mcp_servers.iptime]
command = "node"
args = ["/absolute/path/to/iptime-mcp/dist/server.js"]
cwd = "/absolute/path/to/iptime-mcp"
default_tools_approval_mode = "writes"

[mcp_servers.iptime.env]
IPTIME_ROUTER_ID = "home"
IPTIME_ROUTER_URL = "http://192.168.0.1"
IPTIME_ROUTER_USERNAME = "admin"
IPTIME_ROUTER_PASSWORD = "your-router-password"

Codex、その IDE 拡張機能、および ChatGPT デスクトップアプリは、同じ Codex ホスト上で MCP 設定を共有します。現在のクライアントオプションについては、公式の MCP 設定ガイドを参照してください。

ローカルの .env ファイルを使用する場合は、cwd をそのままにし、[mcp_servers.iptime.env] テーブルを省略してください。

Claude Desktop

設定 → 開発者 → 設定を編集を開き、以下の iptime エントリーを claude_desktop_config.json に統合して保存し、Claude Desktop を完全に再起動してください。ファイルに既存のほかのサーバーがある場合は、そのまま残してください。

{
  "mcpServers": {
    "iptime": {
      "command": "node",
      "args": ["/absolute/path/to/iptime-mcp/dist/server.js"],
      "env": {
        "IPTIME_ROUTER_ID": "home",
        "IPTIME_ROUTER_URL": "http://192.168.0.1",
        "IPTIME_ROUTER_USERNAME": "admin",
        "IPTIME_ROUTER_PASSWORD": "your-router-password"
      }
    }
  }
}

再起動後、チャット作成欄のコネクタを確認してください。詳しくは公式の Claude Desktop ローカル MCP ガイドを参照してください。

Claude Code

Claude Code CLI を使って、すべてのプロジェクトでサーバーを登録します。

claude mcp add \
  --scope user \
  --env IPTIME_ROUTER_ID=home \
  --env IPTIME_ROUTER_URL=http://192.168.0.1 \
  --env IPTIME_ROUTER_USERNAME=admin \
  --env IPTIME_ROUTER_PASSWORD=your-router-password \
  --transport stdio iptime \
  -- node /absolute/path/to/iptime-mcp/dist/server.js

claude mcp get iptime

最後の --transport オプションは、可変長引数の --env パーサーがサーバー名を取り込まないよう、意図的に環境変数の後に置いています。ユーザースコープの設定は ~/.claude.json に保存されます。詳しくは公式の Claude Code MCP ガイドを参照してください。

Cursor

~/.cursor/mcp.json を作成するか、既存の設定に統合してください。この例では、先ほど作成した Git の対象外のローカル .env を読み込みます。

{
  "mcpServers": {
    "iptime": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/iptime-mcp/dist/server.js"],
      "cwd": "/absolute/path/to/iptime-mcp",
      "envFile": "/absolute/path/to/iptime-mcp/.env"
    }
  }
}

Cursor を再起動してから、設定 → ツールと MCPを確認してください。プロジェクトスコープの .cursor/mcp.json にも対応していますが、コミットされる可能性のあるファイルにルーターの認証情報を記載しないでください。詳しくは公式の Cursor MCP ガイドを参照してください。

VS Code エージェントチャット／GitHub Copilot Chat

コマンドパレットから MCP: Open User Configuration を実行し、この設定を統合します。VS Code では、最上位キーとして mcpServers ではなく servers を使用します。

{
  "servers": {
    "iptime": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/iptime-mcp/dist/server.js"],
      "cwd": "/absolute/path/to/iptime-mcp",
      "envFile": "/absolute/path/to/iptime-mcp/.env"
    }
  }
}

MCP: List Servers で起動または状態を確認し、初回使用時にサーバーの信頼を求めるプロンプトを承認します。ワークスペース単位の設定には .vscode/mcp.json を使用できますが、ルーターの認証情報にはユーザー設定のほうが安全です。VS Code の公式 MCP 設定ガイドと設定リファレンスを参照してください。

GitHub Copilot CLI

GitHub Copilot CLI は VS Code の .vscode/mcp.json を読み込みません。代わりに ~/.copilot/mcp-config.json を作成するか、既存の設定に統合してください。

{
  "mcpServers": {
    "iptime": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/iptime-mcp/dist/server.js"],
      "cwd": "/absolute/path/to/iptime-mcp",
      "tools": ["*"]
    }
  }
}

設定した cwd により、iptime-mcp がローカルの .env を読み込めます。copilot mcp list で接続を確認してください。プロジェクトレベルの .mcp.json と .github/mcp.json もサポートされていますが、ルーターの認証情報は絶対にコミットしないでください。Copilot CLI の公式 MCP ガイドを参照してください。

Gemini CLI

~/.gemini/settings.json を作成するか、既存の設定に統合してください。

{
  "mcpServers": {
    "iptime": {
      "command": "node",
      "args": ["/absolute/path/to/iptime-mcp/dist/server.js"],
      "cwd": "/absolute/path/to/iptime-mcp",
      "trust": false
    }
  }
}

設定した cwd により、サーバーが .env を読み込めます。ツール呼び出しの前に Gemini が引き続き確認を求めるよう、trust は false のままにしてから、gemini mcp list を実行してください。現在のフォルダーが信頼されていない場合は、gemini trust を実行します。CLI コマンドのデフォルトはプロジェクトスコープです。手動で登録する場合は --scope user を使用してください。Gemini CLI の公式 MCP ガイドを参照してください。

その他の stdio MCP クライアント

コマンドには node を指定し、唯一の引数として /absolute/path/to/iptime-mcp/dist/server.js を渡し、.env の IPTIME_* 変数を渡してください。すべてのクライアントが同じ JSON ラッパーを使用すると想定しないでください。たとえば、VS Code は servers を使用し、Claude Desktop、Cursor、Copilot CLI、Gemini CLI は mcpServers を使用します。

環境変数

単一のルーター

変数	必須	デフォルト	説明
IPTIME_ROUTER_URL	はい	—	http または https を使用するルーターのベース URL
IPTIME_ROUTER_ID	いいえ	default	router_id として公開されるプロファイル名
IPTIME_ROUTER_USERNAME	ログイン時	—	ルーター管理者のユーザー名
IPTIME_ROUTER_PASSWORD	ログイン時	—	ルーター管理者のパスワード
IPTIME_ALLOW_INSECURE_REMOTE_HTTP	いいえ	false	ホスト名がパブリックアドレスに解決される場合に、平文 HTTP を許可します
IPTIME_TLS_FINGERPRINT	いいえ	—	通常の TLS 検証に加えて照合する SHA-256 証明書フィンガープリント。コロンの有無は問いません
IPTIME_TIMEOUT_MS	いいえ	12000	リクエストのタイムアウト。1,000～60,000 ms の範囲に制限されます

認証情報を IPTIME_ROUTER_URL に埋め込まないでください。

サーバーは、作業ディレクトリにある .env ファイルも読み込みます。ローカルで使用する場合に限り、.env.example を .env にコピーしてください。.env と関連するシークレットファイルは Git の対象外です。

複数のルーター

IPTIME_ROUTERS に JSON 配列を設定します。JSON に認証情報ではなく環境変数名が含まれるよう、username_env と password_env を使用してください。

IPTIME_ROUTERS='[{"id":"home","url":"http://192.168.0.1","username_env":"HOME_ROUTER_USERNAME","password_env":"HOME_ROUTER_PASSWORD"},{"id":"office","url":"https://router.office.example","username_env":"OFFICE_ROUTER_USERNAME","password_env":"OFFICE_ROUTER_PASSWORD","timeout_ms":20000}]'
HOME_ROUTER_USERNAME=admin
HOME_ROUTER_PASSWORD=your-home-password
OFFICE_ROUTER_USERNAME=admin
OFFICE_ROUTER_PASSWORD=your-office-password

ルーターが 1 台設定されている場合、router_id は省略できます。複数のルーターが設定されている場合は、ルーターツールに対象の router_id を渡してください。

MCP ツール

ツール	目的
iptime_status	インターフェースを検出し、認証情報がある場合は認証して、製品／システムのステータスを読み取ります
iptime_login	MCP 環境の認証情報でログインします。必要に応じて CAPTCHA の回答を送信できます
iptime_logout	現在のルーター管理者セッションを終了します
iptime_capabilities	カタログに登録された操作を対象モデルおよびファームウェアに照らして確認します
iptime_list_operations	ローカルの監査可能な操作カタログをドメインまたはモード別に一覧表示します
iptime_read	読み取り専用のカタログ操作を1つ実行します
iptime_backup_config	既存のファイルを上書きせずに、新しい .config バックアップファイルを保存します
iptime_plan_change	適用せずに、汎用的なルーター変更計画を作成します
iptime_plan_firmware_upgrade	ローカルの .bin イメージをハッシュ化し、重大リスクのアップグレード計画を作成します
iptime_plan_config_restore	ローカルの .config バックアップをハッシュ化し、重大リスクの復元計画を作成します
iptime_apply_change	ID を指定して、保留中の計画を1つ適用します。確認トークンは不要です
iptime_cancel_change	保留中の計画をキャンセルします
iptime_list_plans	メモリ上にある保留中および完了済みの計画を一覧表示します

MCP リソース

URI	内容
iptime://configuration	認証情報を除いた、設定済みのルータープロファイル
iptime://operations	操作カタログ全体、ドメイン、モード、リスク、パラメーターのヒント

推奨ワークフロー

1. iptime_status を呼び出してルーターを検出し、セッションを確立します。
2. iptime_capabilities を呼び出します。必要に応じて、wireless、network、vpn、usb などのドメインで絞り込みます。
3. iptime_list_operations を使って、該当する操作とパラメーターのヒントを確認します。
4. iptime_read で読み取りを実行します。
5. 変更する場合は計画を作成し、そのリスク、パラメーター、以前の状態、有効期限をユーザーに提示します。
6. 計画がユーザーの具体的な依頼に合致する場合、トークンや計画 ID の再入力を求めずに適用します。重大リスクの変更が明示的に承認されていない場合に限り、自然な表現で一度だけ確認します。
7. 結果が不明と報告された場合は、ほかの操作を行う前に、返された検証状態を確認します。

読み取りに便利な操作の例：

• product.info および system.info
• network.info および network.interface.lan.stations
• dhcpd.lease.show および dhcpd.reservedaddr.show
• wireless.client.show および wireless.channel.list
• portforward.get および upnp.relay
• firewall.get
• wg.client.show、wg.peer.show、および vpncli.status.list
• ddns.config および ddns.status.get
• usb.show、usb.mount.list、および nas.user.show
• syslog.show および wol.show

一部のメソッドでは、空のオブジェクトではなく、スカラー値、配列、またはオブジェクトが必要です。カタログの paramsHint フィールドと defaultParams フィールドに、既知の規則が記載されています。たとえば、Wi-Fi チャネルの一覧表示には "2g" や "5g" などの帯域が必要で、DDNS ステータスの確認には設定済みのホスト名が必要です。

バックアップ、復元、ファームウェア

iptime_backup_config：

• .config で終わる保存先が必要です
• 必要に応じて親ディレクトリを作成します
• 既存のファイルの上書きを拒否します
• 所有者のみがアクセスできる権限（0600）で書き込みます
• 空のバックアップ、および 32 MiB を超えるファイルを拒否します

設定バックアップには、プライベートなネットワーク設定やシークレットが含まれる場合があります。*.config は Git の対象外であり、コミットしてはいけません。

ファームウェアおよび復元の計画には、ファイルサイズと SHA-256 ハッシュが記録され、アップロードの直前にファイルが再検証されます。ファームウェアイメージは .bin で、設定バックアップは .config で終わる必要があります。ファームウェアイメージはルーターモデルとの互換性が検証されないため、正確なモデルに対応するイメージを入手し、重大リスクの計画を慎重に確認してください。

ネットワークセキュリティ

• IPTIME_ALLOW_INSECURE_REMOTE_HTTP=true の場合を除き、パブリックアドレスへの平文 HTTP は拒否されます。
• このオーバーライドを有効にすると、管理者パスワードやセッション Cookie が漏えいするおそれがあります。HTTPS を利用できない場合に限り、信頼できるプライベートトンネル経由で使用してください。
• リダイレクトと、オリジンをまたぐエンドポイントの構築はブロックされます。
• レスポンスは 8 MiB に制限され、リクエストにはタイムアウトが設定されています。
• 保持されるのは ipTIME セッション Cookie のみです。
• パスワード、トークン、セッション値、秘密鍵、PSK などのフィールドは、MCP の出力から再帰的に秘匿されます。
• TLS フィンガープリントを任意で指定すると、通常の証明書検証後にピンニングが追加されます。信頼されていない自己署名証明書が有効になるわけではありません。

MCP クライアントの設定ファイルにはルーターのパスワードが含まれる場合があるため、秘密情報として扱ってください。

CAPTCHA とセッションの動作

ルーターが CAPTCHA を要求すると、iptime_login は利用可能なチャレンジ情報を含む CAPTCHA_REQUIRED エラーを返します。必要に応じてルーターの管理ページを開き、その後 captcha_code を指定して iptime_login を再試行してください。

期限切れのセッションは、読み取り操作で一度だけ自動更新されます。認証エラーまたはネットワーク上の不確実な状態が発生した後に、書き込み操作が自動で再試行されることはありません。

開発

npm ci
npm run lint
npm test
npm run build

開発モードの場合：

npm run dev

テストスイートではループバックのモックルーターを使用するため、物理デバイスは不要です。本番環境のルーターに対して書き込みテストを実行しないでください。

AI エージェント向けファイル

• llms.txt には、プロジェクトとツールの概要を簡潔にまとめた機械可読情報が記載されています。
• AGENTS.md には、コーディングエージェント向けのリポジトリへの貢献ルールと安全規則が記載されています。
• templates/AGENTS.md は、この MCP サーバーを使用するプロジェクトにコピーできます。
• templates/CLAUDE.md には、Claude Code プロジェクト向けの同等の使用ガイダンスが記載されています。

これらのファイルには、実際のツールのワークフローと安全上の制約が記載されています。認証情報やローカルルーターの詳細は含まれていません。

ライセンス

MIT © 2026 mikusnuz