MikroTik RouterOS

mikrotik-mcp

mcp-name: io.github.StefanKnol/mikrotik-mcp

SSH 経由で CLI を操作するのではなく、バイナリ API を使用する MikroTik RouterOS 向け MCP サーバーです。

この違いが重要なポイントです。CLI が出力するのは 位置を示す 番号であり、ルールの識別子ではありません。位置でルールを一覧表示し、その位置を使って書き込むサーバーは、単に失敗します。where .id=3 は何も一致しないため、明らかに存在するルールへの書き込みがすべて「見つかりません」と報告されます。さらに悪い場合は、順序が変わった後に別のルールへの書き込みが成功してしまいます。ファイアウォールでは、誤ったルールを削除することになります。

バイナリ API は、読み取りのたびに実際の .id（*7、*1f）を返します。そのため、以下が実現できます。

• 読み取りの結果には必ず id が含まれ、書き込みではその値を指定します。
• 一覧表示の結果には position も含まれますが、これは表示専用であり、書き込みでは拒否され、その理由を説明するエラーが返されます。
• 書き込んだ内容を読み戻すため、変更を想定するだけでなく検証できます。
• remove_firewall_rule では省略可能な confirm_comment を指定でき、削除したルールが返されます。

使い方

uvx mikrotik-mcp

環境変数で設定してください。フラグとして渡したパスワードは ps に表示されます。

変数	デフォルト	説明
MIKROTIK_HOST	—	ルーターのアドレスです。必須です。
MIKROTIK_USERNAME	—	必須です。
MIKROTIK_PASSWORD	—
MIKROTIK_PORT	8729	api-ssl の場合は 8729、平文の場合は 8728 です。
MIKROTIK_TLS	true
MIKROTIK_TLS_FINGERPRINT	—	ルーター証明書の SHA-256 値を指定して固定します。
MIKROTIK_TIMEOUT	10

MCP クライアントの設定では、次のように指定します。

{
  "mcpServers": {
    "mikrotik": {
      "command": "uvx",
      "args": ["mikrotik-mcp"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "mcp-agent",
        "MIKROTIK_PASSWORD": "..."
      }
    }
  }
}

ルーター側の設定

/ip service enable api-ssl
/user group add name=mcp policy=api,read,write,test
/user add name=mcp-agent group=mcp password=<strong-password>

api ポリシーは必須です。これが設定されていない場合、誤ったパスワードの場合と同じログインエラーが発生します。そのため、認証情報に問題がないように見えるのにログインできない場合は、まずグループを確認してください。

可能であれば MIKROTIK_TLS_FINGERPRINT を設定してください。MikroTik の API-SSL 証明書は自己署名証明書のため、標準状態のデバイスでは通常の CA 検証に成功しません。証明書を固定することで、接続を単に暗号化するだけでなく、認証された接続にできます。

ツール

システム情報、インターフェイス、IP アドレス設定、ファイアウォールフィルター（IPv4 と IPv6）、ファイアウォールアドレスリスト、NAT、DHCP リース、DNS、ルート、ログを扱う 34 個のツールがあります。さらに、任意の RouterOS パスを読み取る ros_list があり、専用ツールがなくてもすべてを扱えます。

汎用の書き込み手段は意図的に用意していません。

最初に呼び出す前に、次の 3 点を確認してください。

• 書き込みでは position ではなく id（*7）を指定します。 一覧表示の結果には両方が含まれます。position はルールが現在評価順のどこにあるかを示すもので、何かを追加、削除、移動するたびに変わります。また、フィルターで指定したチェーン内ではなく、テーブル全体を通して数えられます。position を書き込みに渡すと、推測で処理するのではなく拒否されます。
• IPv4 と IPv6 は別々のルールセットです。 ファイアウォールツールでは family を指定します。デフォルトは ipv4 なので、デバイスの IPv4 はロックダウンされているように見えても、IPv6 テーブルが空で、すべてを受け入れている場合があります。このため、IPv4 の一覧表示では IPv6 のルール数も報告します。
• アドレスリストには、設定エクスポートには表示されない状態が保持されます。 ルールが実行時に追加するエントリにはタイムアウトがあり、メモリ上にのみ存在します。まず list_address_list_entries に count_only を指定して問い合わせてください。登録済みのブロックリストには、数万件のエントリが含まれることがあります。

mcphub での利用

mcphub は MCP サーバーを単一のサインインの背後に配置し、アカウントごとに利用権限を付与します。1 台のルーターを 1 つのバックエンドとして、それぞれの /mcp/<slug> に登録し、クライアントでは独立したコネクターとして登録します。

追加方法

レジストリから追加 — 通常はこちらがおすすめです。レジストリから追加を選び、mikrotik-mcpを検索すると、ハブがserver.jsonから設定フォームを作成し、バックエンドを有効にしたときにuvx mikrotik-mcpを起動します。専用のプロセスで実行されるため、ハブがほかの用途で保持している認証情報を読み取ることはできません。この方法で追加したバックエンドは無効の状態で起動します。開いてツール一覧を確認してから、有効にしてください。

プラグインとして追加 — このパッケージをハブ自身の環境にインストールすると、mikrotikがバックエンドの種類として表示され、型指定されたフィールドと、ルーターの識別情報およびRouterOSのバージョンを報告するテストボタンが使えるようになります。設定はしやすくなりますが、インプロセスのプラグインはハブが保持するすべての認証情報を読み取ることができます。独自のハブイメージをビルドする場合に使用してください。

設定項目

どちらの方法でも、同じ項目を設定します。環境変数は次のとおりです。

変数	デフォルト
MIKROTIK_HOST	—	ルーターのアドレスです。必須です。
MIKROTIK_USERNAME	—	必須です。adminではなく、専用ユーザーを使用してください。そのユーザーのグループにはapiポリシーが必要です。
MIKROTIK_PASSWORD	—	必須です。
MIKROTIK_PORT	8729	api-sslの場合は8729、平文通信の場合は8728です。
MIKROTIK_TLS	true	無効にすると、ルーターのパスワードがネットワーク上で平文のまま送信されます。
MIKROTIK_TLS_FINGERPRINT	—	ルーターの証明書のSHA-256です。これをピン留めすることで、TLS接続が単に暗号化されるだけでなく、認証されるようになります。
MIKROTIK_TIMEOUT	10	秒単位です。

データディレクトリは不要です。このサーバーが読み書きするデータはすべてルーター上にあるため、ローカルに保持する状態はありません。このサーバーにデータディレクトリを指定するのチェックを外したままにしてください。

権限レベル

ハブは各ツールのreadOnlyHintとdestructiveHintだけを読み取り、それに基づいて付与された権限レベルを適用します。権限レベルを超えるツールはtools/listから除外され、呼び出された場合も拒否されます。

レベル	利用できるツール
viewer	17個のツール	設定全体を読み取り、変更は行いません。
user	+7個のツール	ルールとエントリーを追加し、それらを無効化または再有効化できます。
admin	+10個のツール	削除、直接編集、並べ替えを行えます。

viewer — connectivity_check、get_dns_settings、get_firewall_rule、get_logs、get_nat_rule、list_address_list_entries、list_address_lists、list_dhcp_leases、list_dns_adlist、list_dns_static、list_firewall_rules、list_interfaces、list_ip_addresses、list_nat_rules、list_routes、ros_list、system_info。

userには、add_address_list_entry、add_dns_static、add_firewall_rule、add_nat_rule、make_lease_static、set_firewall_rule_enabled、set_nat_rule_enabledが追加されます。これらはいずれも書き込みを行いますが、何かを削除するものはありません。ルールの追加は書き込みであって、破壊的な操作ではありません。また、無効化してもルール、コメント、位置はそのまま保持されるため、再有効化すると元の状態に正確に戻ります。ルールが何かの原因かどうかを調べるには、無効化する方法が安全で、元に戻すこともできます。そのため、この権限レベルに含まれています。別の方法では、userに安全なテスト手段がなくなってしまいます。

adminには、破壊的な次の10個のツールが追加されます。

ツール	失われるもの
remove_firewall_rule	ルールです。返されたコピーだけが記録として残ります。
remove_nat_rule	ルールです。
remove_dns_static	エントリーです。
remove_address_list_entry	エントリーです。動的なエントリーは、ルールに次に一致したときに戻りますが、静的なエントリーは戻りません。
update_firewall_rule	設定またはクリアした項目の以前の値です。
update_nat_rule	同上です。
update_dns_static	同上です。
move_firewall_rule	以前の順序です。これはファイアウォールの動作そのものを左右します。
move_nat_rule	同上です。
set_interface_enabled	ディスク上のデータは失われませんが、リクエストの受信に使用したインターフェースを無効にすると、戻るための唯一の経路が切断され、このサーバーからリモートで元に戻すことはできません。

テストでは、これらの割り当てを名前ごとにすべて固定しています。そのため、後からツールを追加すると、どの権限レベルに属するかが決定されるまでテストスイートは失敗します。

MCP レジストリへの公開

server.json は公式 MCP レジストリのマニフェストで、公開済みのスキーマに照らして検証されます。uvx mikrotik-mcp コマンドと、各 MIKROTIK_* 変数を宣言し、必須かシークレットかを示します。これにより、このサーバーについて何も知らなくても、レジストリを参照するクライアントが正しい設定フォームを生成できます。

レジストリは、エントリーを公開する人が参照先のパッケージを実際に所有していることを検証するため、公開には順序があります。

1. パッケージは、あらかじめ PyPI に登録されている必要があります。 レジストリは pypi.org/pypi/mikrotik-mcp/<version>/json を取得し、パッケージが存在しないエントリーを拒否します。リリースにタグを付け、CI に公開させます。

git tag v0.1.0 && git push --tags

まず PyPI Trusted Publisher が必要です。このプロジェクトはまだ PyPI に存在しないため、pending publisher として登録する必要があります。プロジェクトごとの Publishing タブはプロジェクト作成後にのみ表示されるため、このページでその鶏と卵の問題を解決します。

pypi.org → アカウント設定 → Publishing → 新しい pending publisher を追加

フィールド	値
PyPI Project Name	mikrotik-mcp
Owner	StefanKnol
Repository name	mikrotik-mcp
Workflow name	ci.yml
Environment name	pypi

環境名は重要です。公開ジョブでは environment: pypi を宣言しており、名前が一致しない場合、PyPI はアップロードを拒否します。

2. README に所有権トークンを記載する必要があります。 レジストリは PyPI の説明文（このファイル）で mcp-name: io.github.StefanKnol/mikrotik-mcp を探します。この記述はファイルの先頭に独立した行としてあります。これにより、レジストリエントリーを公開する人が PyPI パッケージを管理していることを証明します。

3. レジストリエントリーは自動で公開されます。 ci.yml の registry ジョブは、同じタグでの PyPI へのアップロード後に実行され、mcp-publisher login github-oidc で認証します。GitHub が有効期間の短い OIDC トークンに署名し、レジストリがそれを検証して、リポジトリの所有者に基づく io.github.StefanKnol/* 名前空間を付与します。シークレットを保存する必要も、リリースのたびにデバイスフローでログインする必要もありません。

新しいバージョンが PyPI で実際に配信されるまで待機します。レジストリは pypi.org/pypi/mikrotik-mcp/<version>/json を取得し、パッケージを確認できないエントリーを拒否します。このエンドポイントにはアップロードから反映されるまで数秒かかるため、直後に公開すると競合します。

再実行しても問題ありません。すでにレジストリに登録済みのバージョンは、このジョブが作成する結果そのものです。そのため、重複を理由に失敗するのではなく、その旨を報告して成功します。

手動で公開する場合（失敗した実行からの復旧、またはこのジョブができる前にリリースされたバージョン）：

curl -sL https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz | tar xz mcp-publisher
./mcp-publisher login github && ./mcp-publisher publish

login github はデバイスフローを開始し、あなたが StefanKnol であることを証明します。これにより、OIDC の方法で確認なしに取得するものと同じ名前空間への権限が付与されます。

バージョンは pyproject.toml、__version__、server.json、および同ファイル内の packages エントリーの4か所に記載されています。手動で編集する代わりに、次の手順を実行します。

uv run python scripts/release.py 0.2.0 --tag

4か所すべてに値を設定して検証し、コミットしてタグを付けます。レジストリでは各バージョンが個別の行として扱われ、PyPI にそのバージョンのパッケージが正確に存在するか確認されるため、入れ子になった packages[].version もトップレベルの値と同じくらい重要です。マニフェストはこの値がなくても検証に通るため、ここが見落とされがちです。テストで両者が一致することを確認しています。

開発

uv sync --extra dev
uv run pytest

ライセンス

MIT