Cisco Modeling Labs CML

Cisco Modeling Labs (CML) 用 Model Context Protocol (MCP) サーバー

mcp-name: io.github.xorrkaz/cml-mcp

概要

cml-mcp を使えば、AI アシスタントの力をネットワークラボで活用できます。このツールを使うと、Claude Desktop、Claude Code、Cursor などの AI アプリケーションを通じて、自然な言葉で Cisco Modeling Labs (CML) を操作できます。

メニューをクリックしたりスクリプトを書いたりする代わりに、「2 台のルーターで新しいラボを作成して OSPF を設定して」や「Router1 の実行中の設定を表示して」のように、したいことを平易な英語で伝えるだけで、自動的に実行されます。

これは、AI アプリケーションが外部のツールやサービスとやり取りするための標準規格である Model Context Protocol (MCP) を通じて実現されます。AI アシスタントに CML サーバーへの直接接続を与えるものと考えてください。

機能

• ラボトポロジーの作成： 新しいラボを作成し、ゼロから、または完全なトポロジー定義を使ってネットワークトポロジーを定義するツールです。
• ステータスの照会： ラボ、ノード、リンク、注釈、および CML サーバー自体の詳細なステータス情報を取得するツールです。
• ラボとノードの制御： 必要に応じて、ラボまたは個々のノードを起動、停止、消去するツールです。
• CML ユーザーとグループの管理： ローカルユーザーとグループを一覧表示、作成、削除するツールです（管理者権限が必要です）。
• 視覚的な注釈： ドキュメント作成や整理のために、ラボトポロジーに視覚要素（テキスト、長方形、楕円、線）を追加します。
• リンクの管理： ノードを接続し、リンクの状態調整（帯域幅、遅延、ジッター、損失）を設定し、リンクの状態を制御します。
• パケットキャプチャ： ネットワークリンクのパケットキャプチャ（PCAP）を開始、停止、取得し、Wireshark などのツールでトラフィックを分析します。
• ノード設定： ノードの起動時設定を構成し、稼働中のデバイスに CLI コマンドを送信します。
• デバイスでのコマンド実行： PyATS を使って、MCP クライアントが CML ラボ内の仮想デバイスでコマンドを実行できます。
• コンソールログへのアクセス： 稼働中のノードのコンソールログを取得して、トラブルシューティングや監視に利用できます。特定のシリアルコンソールポートを選択することもできます。
• モジュール型アーキテクチャ： 保守性と拡張性を高めるため、ツールは論理的なモジュール（ラボ、ノード、リンク、pcap など）に整理されています。
• アクセス制御リスト（HTTP モード）： HTTP トランスポートモードで実行する場合、YAML ベースの ACL 設定ファイルを使って、ユーザーごとにアクセス可能なツールを制限できます。
• オブザーバビリティ： オプションの OpenTelemetry トレーシングにより、各ツール呼び出しのスパンを OTLP 対応バックエンド（Jaeger、Grafana Tempo、Datadog など）にエクスポートできます。

クイックスタート

インストール

最も簡単に始めるには、Claude Desktop（またはその他の MCP 対応クライアント）で uvx を使用します。uvx ツールは、手動でインストールしなくてもサーバーを自動的にダウンロードして実行します。

設定： Claude Desktop の設定ファイル（claude_desktop_config.json）を見つけて編集します。以下を追加してください。

{
    "mcpServers": {                                                               
        "Cisco Modeling Labs CML": {                                                                
          "type": "stdio",                                                          
          "command": "uvx",
          "args": [                                                                 
            "cml-mcp"                                                        
          ],                                                                        
          "env": {
            "CML_URL": "{CML_URL}",                           
            "CML_USERNAME": "{CML_USERNAME}",                                                 
            "CML_PASSWORD": "{CML_PASSWORD}!",
            "CML_VERIFY_SSL": "true"
          }                                                                         
        }
    }
}

重要： プレースホルダーの値を、実際の CML サーバーの情報に置き換えてください。

• CML_URL：CML サーバーのアドレス（例：https://cml.example.com または https://10.10.20.50）
• CML_USERNAME と CML_PASSWORD：CML のログイン認証情報
• CML_VERIFY_SSL：TLS 証明書の検証は、デフォルトで "true" になりました。CML には自己署名証明書が標準で付属しているため、ほとんどのユーザーはこれを "false" に設定する必要があります。CML サーバーに CA 署名済み証明書をインストールしている場合（または自己署名証明書を含むファイルを CA_BUNDLE に指定している場合）にのみ、"true" のままにしてください。

ヒント

uvx で「コマンドが見つかりません」と表示されますか？ Claude Desktop などの MCP クライアントは制限された環境で実行されるため、シェルの PATH を常に引き継ぐとは限りません。uvx が見つからない場合は、"command" フィールドにフルパスを指定してください。パスを確認するには、macOS/Linux ではターミナルで which uvx を、Windows ではコマンドプロンプトで where uvx を実行します（例：macOS では "/Users/alice/.local/bin/uvx"、Windows では "C:\Users\alice\.local\bin\uvx.exe"）。同じことは、MCP の設定で使用する uv、npx、その他のコマンドにも当てはまります。

さらに多くの機能が必要ですか？

• デバイスの CLI コマンド実行には、引数で cml-mcp の代わりに cml-mcp[pyats] を使用してください
• Docker、Windows（WSL）、または HTTP サーバーモードについては、INSTALLATION.md を参照してください

設定ファイルの場所：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

要件

• Python 3.12、3.13、または 3.14
• Cisco Modeling Labs（CML）2.9 以降
• uv - Python パッケージマネージャー

利用可能な MCP ツール

サーバーは、以下のカテゴリに分類された 51 個の MCP ツールを提供します。

ラボ管理

• get_cml_labs - 特定のユーザーまたは現在のユーザーのラボを取得します
• create_empty_lab - オプションのメタデータを指定して、新しい空のラボを作成します
• create_full_lab_topology - トポロジー定義から完全なラボを作成します
• modify_cml_lab - ラボのプロパティ（タイトル、説明、メモ）を更新します
• set_cml_lab_permissions - グループ／ユーザーのアクセス権（LAB_ADMIN、LAB_EDIT、LAB_EXEC、LAB_VIEW）を設定します
• start_cml_lab - ラボ内のすべてのノードを起動します
• stop_cml_lab - ラボ内のすべてのノードを停止します
• wipe_cml_lab - すべてのノードのデータ／設定を消去します（クライアントが対応している場合は、確認を求めます）
• delete_cml_lab - ラボを削除します（クライアントが対応している場合は、確認を求めます）
• get_cml_lab_by_title - タイトルでラボを検索します
• download_lab_topology - ラボのトポロジーを YAML ファイルとしてダウンロードします
• clone_cml_lab - オプションで新しいタイトルを指定して、ラボを複製します

ノード管理

• get_cml_node_definitions - 利用可能なノードタイプを一覧表示します
• get_node_definition_detail - 特定のノードタイプの詳細情報を取得します
• add_node_to_cml_lab - ラボにノードを追加します
• get_nodes_for_cml_lab - ラボ内のすべてのノードを運用データとともに取得します
• configure_cml_node - ノードの起動時設定を指定します
• start_cml_node - 指定したノードを起動します
• stop_cml_node - 指定したノードを停止します
• wipe_cml_node - ノードのデータを消去します（クライアントが対応している場合、確認を求めます）
• delete_cml_node - ノードを削除します（クライアントが対応している場合、確認を求めます）
• get_console_log - ノードのコンソール出力履歴を取得します。省略可能なconsoleインデックスでシリアルポートを選択します（デフォルトは0です。Docker ベースのノードでは多くの場合、0と1の両方を使用します）
• send_cli_command - 稼働中のノードで CLI コマンドを実行します（PyATS が必要です）。省略可能なconsoleインデックスで使用するシリアルポートを選択します

インターフェイスとリンクの管理

• add_interface_to_node - ノードにインターフェイスを追加します。作成されたインターフェイスの一覧を返します（ノードタイプによっては、1つのスロット要求で複数のインターフェイスが追加される場合があります）
• get_interfaces_for_node - ノードのすべてのインターフェイスを取得します
• connect_two_nodes - 2つのインターフェイス間にリンクを作成します
• get_all_links_for_lab - ラボ内のすべてのリンクを取得します
• apply_link_conditioning - ネットワーク条件（帯域幅、遅延、ジッター、損失）を設定します
• start_cml_link - リンクの接続を有効にします
• stop_cml_link - リンクの接続を無効にします

アノテーション（視覚要素）

• get_annotations_for_cml_lab - ラボ内のすべての視覚的なアノテーションを取得します
• add_text_annotation - テキストアノテーションを追加します
• add_rectangle_annotation - 長方形のアノテーションを追加します
• add_ellipse_annotation - 楕円のアノテーションを追加します
• add_line_annotation - 線のアノテーションを追加します
• delete_annotation_from_lab - アノテーションを削除します（クライアントが対応している場合、確認を求めます）

パケットキャプチャ（PCAP）

• start_packet_capture - リンク上でパケットのキャプチャを開始します
• stop_packet_capture - 実行中のパケットキャプチャを停止します
• check_packet_capture_status - キャプチャのステータスとパケット数を確認します
• get_captured_packet_overview - キャプチャしたパケットの概要を取得します
• get_packet_capture_data - PCAP ファイル全体をダウンロードします（Wireshark/tcpdump 用に Base64 エンコードされます）

ユーザーとグループの管理

• get_cml_users - すべての CML ユーザーを一覧表示します
• create_cml_user - 新しいユーザーを作成します（管理者権限が必要です）
• delete_cml_user - ユーザーを削除します（管理者権限が必要です。クライアントが対応している場合、確認を求めます）
• get_cml_groups - すべての CML グループを一覧表示します
• create_cml_group - 新しいグループを作成します（管理者権限が必要です）
• delete_cml_group - グループを削除します（管理者権限が必要です。クライアントが対応している場合、確認を求めます）

システム情報

• get_cml_information - CML サーバーのバージョンと設定を取得します
• get_cml_status - システムの健全性を示す指標を取得します
• get_cml_statistics - リソース使用状況とラボ／ノード／リンクの数を取得します
• get_cml_licensing_details - ライセンス情報と上限を取得します

使用方法

設定が完了したら、MCP クライアント（例：Claude Desktop）を再起動して、チャットを始めましょう。AI アシスタントが CML サーバーに直接アクセスできるようになり、自然な会話を通じてネットワークラボの構築と管理を支援します。

できること

試してみるプロンプトの例を以下に示します。

はじめに：

• 「自分の CML ラボをすべて表示して」
• 「CML で利用できるノードタイプを教えて」
• 「CML サーバーのステータスとライセンスについて教えて」

ラボの構築：

• 「『OSPF Test Lab』という名前の新しいラボを作成して」
• 「CSR1000v ルーターを 2 台と外部コネクターをラボに追加して」
• 「Router1 の GigabitEthernet1 と Router2 の GigabitEthernet1 を接続して」

設定とテスト：

• 「両方のルーターで OSPF エリア 0 を設定して」
• 「ラボのすべてのノードを起動して」
• 「Router1 の OSPF ネイバーを表示して」
• 「ルーター間のリンクでパケットキャプチャを開始して」

ワークフロー全体の例：

完全なラボを構築してテストする一連のプロンプトを示します。

1. 「『My Network Lab』という名前の新しい CML ラボを作成して」
2. 「IOL ルーターを 2 台、非管理型スイッチを 1 台、外部コネクターを 1 つ、このラボに追加して」
3. 「2 台の IOL ルーターを非管理型スイッチに接続して、スイッチを外部コネクターに接続して」
4. 「接続されているインターフェイスに 192.0.2.0/24 サブネット内の IP アドレスが割り当てられるようにルーターを設定して、OSPF も設定して」
5. 「ラボを起動して、OSPF が正しく動作していることを確認して」
6. 「2 台の IOL ルーターを囲む緑色のボックス注釈を追加して、ラベルを『OSPF Area 0』にして」

Claude Desktop での動作を紹介するデモをご覧ください。

システムプロンプト

LLM ツールがシステムプロンプトに対応している場合や、より豊富な初期コンテキストを指定したい場合は、Hank Preston 提供の以下の例をご利用ください。

あなたは、Cisco Modeling Labs（CML）のサポートを専門とするネットワークラボアシスタントです。次のような、一般的なラボ作業の多くを自然言語インターフェイスで支援します。

• 新しいラボの作成
• ラボへのノードの追加
• ノード間のインターフェイスの作成
• ノードの設定
• 注釈の作成

CML サーバーにアクセスするためのツールを利用できます。

コントリビューション

コントリビューションを歓迎します。ガイドラインについては、CONTRIBUTING.md をご覧ください。

開発環境のセットアップ、テスト、コードスタイルについては、DEVELOPMENT.md をご覧ください。

トラブルシューティング

よくある問題

「Module not found」またはインポートエラー

PyATS のサポートが必要な場合は、すべての追加機能とともにパッケージをインストールしたことを確認してください。

uvx cml-mcp[pyats]  # For uvx installations

SSL 証明書エラー

TLS 証明書の検証はデフォルトで有効です（CML_VERIFY_SSL=true）。CML には自己署名証明書が付属しているため、検証が失敗し、最初から SSL エラーが発生します。検証を無効にするには、環境設定で CML_VERIFY_SSL=false を設定してください。または、CML サーバーに CA 署名済み証明書をインストールしてください（代わりに、自己署名証明書を含むファイルを CA_BUNDLE に設定することもできます）。

PyATS コマンドの実行に失敗する

1. cml-mcp[pyats] を使って PyATS がインストールされていることを確認してください
2. PYATS_USERNAME、PYATS_PASSWORD、PYATS_AUTH_PASS が正しく設定されていることを確認してください
3. Windows では、PyATS のサポートに WSL または Docker を使用してください

トラブルシューティングの詳細については、INSTALLATION.md をご覧ください。

オブザーバビリティ

cml-mcp は、すべてのツール呼び出しについてトレーススパンをエクスポートできるため、オブザーバビリティバックエンド（Jaeger、Grafana Tempo、Datadog など）でリクエストのレイテンシや失敗を確認できます。デフォルトでは無効で、有効にするまではオーバーヘッドも発生しません。

有効にするには、opentelemetry エクストラをインストールし、2 つの環境変数を設定します。

uvx cml-mcp[opentelemetry]

PyATS も必要ですか？エクストラはカンマ区切りで指定します：uvx cml-mcp[pyats,opentelemetry]。

"env": {
    "ENABLE_OTEL": "true",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
}

ローカルのトレースビューアーの実行方法を含む設定の詳細については、INSTALLATION.md を参照してください。

ヘルプを得る

• 既知の問題については、Issues ページを確認してください
• バグの報告方法については、CONTRIBUTING.md を参照してください

ドキュメント

• INSTALLATION.md - すべてのプラットフォームとトランスポートモードに対応した詳細なインストール手順
• DEVELOPMENT.md - 開発環境のセットアップ、テスト、コントリビューションのガイドライン
• CONTRIBUTING.md - プロジェクトへの貢献方法
• examples/skill/cml/SKILL.md - CML を効果的に使用する方法（トポロジー設計、レイアウト、運用）のガイダンスをこの MCP サーバーに補う、エージェントスキルの例
• examples/skill/INSTALL.md - 例のスキルを Claude Code、Claude Desktop、Cursor、VS Code + GitHub Copilot にインストールする方法

ライセンス

このプロジェクトの MCP サーバー部分は、BSD 2-Clause "Simplified" License に基づいてライセンスされています。ただし、CML 自体の pydantic スキーマ型定義コードを利用しており、これはプロプライエタリな Cisco ライセンスの対象です。