mikrotik-rest-mcp

English | Русский

MikroTik REST MCP

RouterOS 7 デバイスの REST API 経由で、コーディングエージェントに構造化されたアクセスを提供する MCP サーバーです。読み取り、条件付きクエリ、ガード付き書き込み、スケジュールされたロールバックガード、コンテナーシェル、ファイル転送に対応します。stdio 経由の単一の MCP サーバーです。

実際の運用作業向けに構築されており、エージェントはルーターのインベントリを取得し、ファイアウォールやルーティングの状態を比較し、コンテナーを操作し、カウンターを監視し、変更を適用できます。影響の大きい操作の前には、人間による確認を必須とします。

機能

• 幅広い読み取り範囲
  • ファイアウォール、ルート、DHCP、DNS、インターフェース、WireGuard、コンテナ、スケジューラー、ログ、システムリソースなど、一般的なコレクション向けに厳選された約60個のget_*ツールがあります。
  • さらに200以上のget_*エンドポイントも、同じフィルターパイプラインを通じて名前で呼び出せます。ツールスキーマを小さく保つため、あえて一覧には記載していません。catalog_searchを使うと見つけられます。
  • routeros_getは任意の/rest/パスを直接受け付けます。また、1回の呼び出しで最大16件の読み取りを並列実行するrouteros_batchもあります。
• 強力なクエリ機能
  • __contains、__in、__not、__gt、__gte、__lt、__lte、__startswith、__endswithを使ったクライアント側のwhereフィルター。
  • fieldsによる射影、sort_by、limit、compact（項目ごとに1行で出力し、多くのトークンを節約します）。
  • RouterOS ネイティブの.proplist／.queryによるサーバー側フィルタリングのパススルー。
• 保護された変更操作
  • MIKROTIK_MODE=readonly：変更／実行ツールは一切登録されません。ポリシーで制限されるだけではなく、プロトコルのインターフェース自体が読み取り専用になります。
  • MIKROTIK_MODE=careful（デフォルト）：破壊的と分類された操作はrequires_confirmationを返します。エージェントはこれをユーザーに伝え、承認後にconfirm: trueを指定して再実行します。対応クライアントでは、MCP のエリシテーションによりネイティブダイアログが表示されます。確認フラグはUX上のゲートであり、セキュリティ境界ではありません。エージェントを実際に制限するのは RouterOS アカウントの権限です。
  • メソッドを考慮したポリシー：PUTは既知のコレクションに限り、PATCH／DELETEはcollection/<id>の項目に限り、POSTは明示的なアクション許可リスト（ping、traceroute、fetch、file/read、script/run、dns flush、backup/save、export、コンテナシェル。catalog.pyを参照）に限られます。
  • MIKROTIK_STRICT_CONFIRM=1を設定すると、すべての変更操作に確認が必要になります。
  • MIKROTIK_MODE=yoloではすべてのゲートが解除され、別のフル権限アカウント（MIKROTIK_YOLO_USERNAME／MIKROTIK_YOLO_PASSWORD_FILE）への切り替えも可能です。監督下で自動化を行う場合に限って使用してください。
• スケジュールされたロールバックガード（RouterOS セーフモードではありません。通常のREST経由で動作します）
  • apply_safeは対象のスナップショットを取得し、ルーター上のスケジューラーを設定してから変更を適用します。設定後は、ロールバックは MCP プロセスやクライアントの稼働状態に依存しなくなります。window_seconds以内にcommit_safeを実行すると、ロールバックが解除されます。
  • 対応メソッド：PATCH（変更されたフィールドのスナップショット値を復元します。トランザクションではなく、同時編集も検出しません）とDELETE（ベストエフォートで再作成します。リスト内の位置と自動生成フィールドは保持されず、応答にその旨が記載されます）。作成された項目の.idは作成後でなければ分からないため、PUTは拒否されます。
  • 伝送エラーの結果が不明な場合、ロールバックは解除せず、そのまま有効に保ちます。解除に失敗した場合、commit_safeは再試行できるよう保留中の記録を保持します。
  • safe_statusは現在有効なロールバックを報告します。
• コンテナと診断
  • container_shellは、名前または.idを指定して RouterOS コンテナ内でコマンドを実行します。デフォルトでは無効（MIKROTIK_ENABLE_CONTAINER_SHELL）で、careful モードでは確認が必要です。また、汎用のrouteros_write経路からこのフラグを回避することはできません。長時間実行するコマンドでは、timeout_secondsでRESTタイムアウトを上書きできます。
  • container_apply_safe／container_commit_safe — コンテナ内でトランザクション的にシェルコマンドを実行します。snapshot_pathsのスナップショットを取得してから変更を実行し、失敗した場合はcheck_cmdによって直ちにロールバックします。コミットが間に合わなければ、繰り返し実行される RouterOS スケジューラーのウォッチドッグがスナップショットを復元します。1つのコンテナで同時に実行できるトランザクションは1つです。
  • interface_trafficはサンプリング期間中のライブなrx／tx bpsおよびppsを測定し、routeros_watchはサンプル間の数値フィールドの差分を表示します。手動で2回読み取らなくてもカウンターの差分を取得できます。
  • run_ping、run_traceroute、run_fetch、run_wifi_monitor、describe_path（フィルターを書く前にフィールドを確認します）。
• サンドボックス付きファイル操作
  • RouterOS 側でのファイルの作成／読み取り／更新／名前変更／削除に加え、チャンク単位のdownload_file／upload_fileに対応します。
  • ホストのファイルシステムへのアクセスはデフォルトで無効です。MIKROTIK_ENABLE_LOCAL_FILESとMIKROTIK_LOCAL_ROOTを設定すると、1つのディレクトリ内に制限できます。転送サイズは8 MiBまでで、既存のローカルファイルを置き換えるにはdownload_fileでoverwrite: trueを指定する必要があります。
• シークレットの保護
  • 認証情報はMIKROTIK_PASSWORD_FILE（推奨）またはMIKROTIK_PASSWORDから取得します。
  • すべての応答は、password／secret／psk／token／private-keyに該当するフィールドをマスクするスクラバーを通ります（MIKROTIK_REDACT=0で無効化できます）。秘匿化はフィールド名に基づいて行われるため、自由形式のテキスト（コメント、スクリプト本文、ログ行、ファイル内容）に含まれるシークレットは確実に検出できません。
  • すべてのツールにツールアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）があり、クライアント側で独自のポリシーを適用できます。

要件

• Python 3.10+（3.13 で開発）。
• REST に到達可能な RouterOS 7.1+（7.24.5、hAP ax³ で統合テスト済み — REST、コンテナー、スケジューラーのロールバック、ファイル操作）。HTTPS には www-ssl を推奨します。www 経由のプレーン HTTP は RouterOS 7.9+ で必要となり、隔離ネットワークでのみ使用してください。REST は Basic 認証を使用するため、通信上で読み取り可能です。
• 読み取り専用で使用する場合は、read + api + rest-api を持つ RouterOS ユーザー。変更や診断を行う場合は write + test を追加し、ファイルツール（download_file、/file/read）には ftp を追加してください。スクリプトエントリーには独自の policy 属性があり、実行するためにアカウントに必要なのは write のみです。また、アカウントが持つものより広いポリシーのスクリプトは実行できません。

インストール

pipx install mikrotik-rest-mcp-server   # or: uvx mikrotik-rest-mcp-server

これにより、mikrotik-rest-mcp-server コンソールスクリプトが公開されます。開発の場合：git clone + pip install -e .

設定

MCP クライアントでサーバーを指定します。

{
  "mcpServers": {
    "mikrotik_rest": {
      "command": "mikrotik-rest-mcp-server",
      "env": {
        "MIKROTIK_BASE": "https://192.168.88.1",
        "MIKROTIK_USERNAME": "mcp-agent",
        "MIKROTIK_PASSWORD_FILE": "/path/to/password-file"
      }
    }
  }
}

変数の一覧（モード、機能フラグ、タイムアウト、TLS 検証）については .env.example を参照してください。

推奨する RouterOS アカウント

# ops account — reads, config writes, diagnostics; no user/policy management,
# no sensitive fields, no reboot
/user group add name=agent policy=read,write,api,rest-api,test,ftp
/user add name=mcp-agent group=agent password=<random>

# monitoring-only account (pair with MIKROTIK_MODE=readonly)
/user group add name=monitor policy=read,api,rest-api,test

yolo モードでは、full 権限を持つ 2 つ目のアカウントを作成し、MIKROTIK_YOLO_* を通じて接続してください。ファイルツールが不要な場合は ftp を省略してください。

エージェントでの使用方法

エージェントが通常たどるフロー：

get_dhcp_leases {compact: true}                     → quick device list
routeros_batch {requests: [...]}                    → status in one call
describe_path {path: "/rest/interface/ethernet"}    → field names before filtering
interface_traffic {name: "ether1", seconds: 2}      → live throughput
routeros_watch {path: ..., diff: true}              → counter deltas
routeros_write {method: "PATCH", ...}               → routine config edit
routeros_write {method: "DELETE", ...}              → stops for confirmation
apply_safe {method: "PATCH", path: "…/<.id>", window_seconds: 60}
                                                    → rollback armed on router; commit_safe to keep

run_script_inline は一時的な RouterOS スクリプトを作成して実行し、削除します（careful モードでは必ず確認されます）。container_shell とホストとのファイル転送には、オプトインフラグが必要です。

ディレクトリ構成

src/mikrotik_rest_mcp/
  client.py      — REST transport, TLS, env config
  catalog.py     — endpoint/tool tables (pure data)
  policy.py      — risk tiers, confirmation gate, mutation allowlist
  output.py      — secret redaction, filters, compact serialization
  files.py       — local file sandbox + router file helpers
  safe_apply.py  — snapshot/rollback machinery
  server.py      — tool list, dispatch, resources, entrypoint

テスト

pytest tests/

ユニットテストはルーターなしで実行できます（REST 呼び出しはモック化されています）。

セキュリティ

SECURITY.md を参照してください。自分が管理していないルーターには接続しないでください。yolo は装填済みの銃、container_shell はリモートコード実行として扱ってください（実際にそうであるためです）。