pyATS MCP サーバー

Cisco pyATS と Genie は、すでにネットワークとの対話方法を知っています — show コマンドの解析、設定の投入、機能状態の学習、宣言的テストの実行などです。しかし、AI エージェントがそれらのいずれかを直接操作する方法はありませんでした。このサーバーはそのギャップを埋めます。pyATS/Genie を、Claude のようなエージェントが実際のテストベッドに対して呼び出せる、構造化されガードされた MCP ツール群としてラップし、Model Context Protocol の現在の Streamable HTTP トランスポート上で動作させます。

エージェントをこのサーバーに向けると、デバイスの検索、show コマンドの実行と解析、ロールバックポイント付きの設定適用、変更前後の機能状態の学習と差分取得、フリート全体へのコマンドのファンアウト（デバイスごとにスレッドプールまたはプロセスを1つ使用）、宣言的 Blitz または Robot Framework テストの実行、デバイスの REST/RESTCONF API の直接呼び出しが可能になります。リスクのあるすべての経路はデバイスに到達する前にガードされ、すべての呼び出しはインメモリの監査ログに記録され、エージェントはセッション中にいつでも確認できます。

概要

• トランスポート — Streamable HTTP（mcp>=2.0.0）、ステートフルまたはステートレス、1つの環境変数で選択可能。STDIO は廃止されました。

• 26 のツール — ディスカバリ、show コマンド、設定、Genie learn/diff、Genie Clean、宣言的テスト（Blitz、Robot Framework、AEtest）、汎用 REST/RESTCONF、Cisco XPresso をカバー。

• 2 つのファンアウト方法 — 複数デバイスへのコマンド展開。日常的な使用には共有スレッドプール、大規模な真の分離が必要な場合にはデバイスごとに 1 つの OS プロセス（pyats.async_.pcall）。

• 信用ではなくガードレール — 危険なコマンドはデバイスに到達する前にブロックされ、Genie Clean がデバイスを再起動または再イメージ化するステージを実行することは決してなく、破壊的な操作には正確な確認フレーズが必要です。

• ハードコードなし — すべての認証情報とデバイス詳細は .env に格納され、実行時に %ENV{} 置換によって testbed.yaml に取り込まれます。

Related MCP server: network-mcp

前提条件

• Python 3.10 以上

• 実在または仮想のネットワークデバイスを指す pyATS testbed.yaml — 物理ラボ、Cisco Modeling Labs / VIRL / GNS3、または Unicon が SSH/Telnet で到達できるその他の環境。pyATS MCP はネットワークをシミュレートするのではなく、実際に駆動します。

• 通信するための MCP 対応クライアント — 下記のエージェントの接続を参照してください。

クイックスタート

# 1. Clone and install
git clone https://github.com/automateyournetwork/pyATS_MCP
cd pyATS_MCP
pip install -r requirements.txt

# 2. Configure your environment
cp .env.example .env
# Edit .env — see Configuration below

# 3. Run — starts a Streamable HTTP server on 0.0.0.0:8080 by default
python3 pyats_mcp_server.py

MCP エンドポイントは http://<host>:<port>/mcp で到達可能になります。

設定

すべてのデバイス詳細と認証情報は .env ファイルに格納されます — リポジトリ内にハードコードされたものはありません。

1. テンプレートをコピー

cp .env.example .env

2. サーバー変数を設定

PYATS_TESTBED_PATH=/absolute/path/to/your/testbed.yaml
PYATS_MCP_ARTIFACTS_DIR=          # default: ~/.pyats-mcp/artifacts
PYATS_MCP_KEEP_ARTIFACTS=1        # 1 = keep, 0 = delete after each run
PYATS_MCP_TESTBED_CACHE_TTL=30    # seconds before testbed reloads from disk
PYATS_MCP_CONN_CACHE_TTL=0        # seconds to keep connections alive (0 = off)
PYATS_MCP_OP_LOG_MAX=500          # max entries in the in-memory operation log

# Transport (Streamable HTTP only — STDIO is not supported)
PYATS_MCP_TRANSPORT_MODE=stateful # stateful (default) | stateless
PYATS_MCP_HTTP_HOST=0.0.0.0
PYATS_MCP_HTTP_PORT=8080

# Optional — only needed for pyats_xpresso_request
XPRESSO_URL=
XPRESSO_API_TOKEN=
XPRESSO_GROUP=

PYATS_MCP_TRANSPORT_MODE=stateless は Streamable HTTP トランスポートで stateless_http=True を設定するため、旧来のハンドシェイクベースのプロトコルをまだ使用しているクライアントからのリクエスト間でサーバー側のセッション状態が保持されません。現在の MCP プロトコル（2026-07-28、SEP-2575）を話すクライアントは、この設定に関係なくデフォルトでハンドシェイク不要です — これはここで設定されたものではなく、mcp>=2.0.0 SDK 自体に由来します。

3. デバイスごとにブロックを追加

testbed.yaml 内のすべてのデバイスは %ENV{VAR} 置換を使用するため、認証情報と接続詳細は実行時に .env から読み取られます。

{DEVICENAME}_{FIELD} 命名規則を使用します：

# Supported os values: iosxe | iosxr | nxos | ios | eos | junos | panos | linux | windows
# Set os=generic and platform="" to let Unicon autodetect on first connect.

CORE1_IP=10.1.1.1
CORE1_PORT=22
CORE1_OS=iosxe
CORE1_PLATFORM=cat9k
CORE1_USERNAME=admin
CORE1_PASSWORD=s3cr3t
CORE1_ENABLE_PASSWORD=s3cr3t

FW1_IP=10.1.1.2
FW1_PORT=22
FW1_OS=panos
FW1_PLATFORM=
FW1_USERNAME=admin
FW1_PASSWORD=s3cr3t
# (no enable password for Palo Alto)

LINUX1_IP=10.1.1.3
LINUX1_PORT=22
LINUX1_OS=linux
LINUX1_PLATFORM=ubuntu
LINUX1_USERNAME=admin
LINUX1_PASSWORD=s3cr3t
# (no enable password for Linux)

デバイスのグループが認証情報を共有する場合は、グループレベルの変数を定義して複数のデバイスで参照します：

SITE_A_USERNAME=netops
SITE_A_PASSWORD=s3cr3t
SITE_A_ENABLE_PASSWORD=s3cr3t

4. testbed.yaml で変数を参照

devices:
  CORE1:
    alias: "Core Switch 1"
    type: "switch"
    os: "%ENV{CORE1_OS}"
    platform: "%ENV{CORE1_PLATFORM}"
    credentials:
      default:
        username: "%ENV{CORE1_USERNAME}"
        password: "%ENV{CORE1_PASSWORD}"
      enable:
        password: "%ENV{CORE1_ENABLE_PASSWORD}"
    connections:
      cli:
        protocol: ssh
        ip: "%ENV{CORE1_IP}"
        port: "%ENV{CORE1_PORT}"
        arguments:
          connection_timeout: 360

OS が不明なデバイスの場合は、os: "%ENV{DEVICE_OS}" を設定し、.env で DEVICE_OS=generic を指定します。 また、必要に応じて arguments: の下に learn_os: true を追加すると、Unicon が初回接続後に OS を検出してキャッシュします。

Docker

ビルド

docker build -t pyats-mcp-server .

実行（.env を直接渡す）

docker run -p 8080:8080 --rm \
  --env-file /absolute/path/to/.env \
  -v /absolute/path/to/testbed.yaml:/app/testbed.yaml \
  pyats-mcp-server

いずれの場合も、サーバーは一度起動してクライアントを向ける長期実行プロセスであり、エージェントがセッションごとに起動するものではありません。各クライアントの接続方法の詳細は下記を参照してください。

エージェントの接続

サーバーが公開するものは1つだけです：http://<host>:<port>/mcp の MCP エンドポイント（Streamable HTTP）。下記の各クライアントはその URL だけが必要です — command/args も、クライアントが管理するローカルプロセスも不要です。

Claude Code

claude mcp add --transport http pyats http://localhost:8080/mcp

# Behind auth (e.g. a reverse proxy in front of the server)
claude mcp add --transport http pyats http://localhost:8080/mcp \
  --header "Authorization: Bearer your-token"

または、.mcp.json（プロジェクトスコープ、リポジトリにコミット）または ~/.claude.json（ユーザースコープ）に直接追加します：

{
  "mcpServers": {
    "pyats": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}

VS Code（GitHub Copilot Chat）

ワークスペースに .vscode/mcp.json を追加します（またはコマンドパレットから MCP: Add Server を実行）：

{
  "servers": {
    "pyats": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}

OpenAI Codex CLI

codex mcp add pyats --url http://localhost:8080/mcp

または ~/.codex/config.toml に：

[mcp_servers.pyats]
url = "http://localhost:8080/mcp"

Claude Desktop

Claude Desktop の claude_desktop_config.json は stdio のみ対応です — url フィールドを入れても機能しません（既知の問題であり、サポートされている方法ではありません）。リモート/HTTP サーバーは代わりに、設定 → コネクタの下のカスタムコネクタとして追加され、Desktop はローカルマシンではなく Anthropic のクラウドから接続します — そのため、localhost ではなく、実際に公開到達可能な HTTPS URL が必要です。

それでも自分のマシンで実行中のサーバーに Desktop を向けるには、mcp-remote をローカル stdio プロキシとしてブリッジします：

{
  "mcpServers": {
    "pyats": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp", "--transport", "http-only"]
    }
  }
}

生の Python（LangGraph、カスタムエージェント、その他）

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8080/mcp") as (read, write, _session_id):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            result = await session.call_tool(
                "pyats_run_show_command",
                arguments={"device_name": "CORE1", "command": "show version"},
            )

何を依頼できるか

接続したら、ネットワークをすでに知っている人に話しかけるように話しかけてください：

• 「テストベッドにはどのデバイスがありますか？」 → pyats_list_devices

• 「CORE1 の BGP サマリーを見せて」 → pyats_run_show_command、構造化 JSON に解析

• 「CORE1 の OSPF 状態をスナップショットして、この設定を適用して変更点を見せて」 → pyats_learn_feature（変更前）→ pyats_configure_with_diff → pyats_learn_feature（変更後）→ pyats_diff_learned_snapshots

• 「すべてのスイッチで show ip interface brief を実行して」 → pyats_run_show_command_multi（大規模な真の分離が必要な場合は pyats_pcall_show_command）

• 「その設定変更で何か壊れたらロールバックして」 → pyats_rollback_config

• 「この Blitz テストを R1 と R2 に対して実行して」/「この Robot Framework スイートを実行して」 → pyats_run_blitz / pyats_run_robot

エージェントはこれらを自分で連鎖させます — 結果を説明すれば、ツールを選択します。

利用可能なツール

機能別にグループ化された 26 のツール。

ディスカバリ

show コマンド

設定

状態と診断

テストと自動化

API

セッション

セキュリティ

• Show コマンドは検証されます — パイプ、リダイレクト、危険なキーワードはブロックされます。

• 設定変更は reload、erase、write erase、delete、format についてチェックされます — 同じチェックが pyats_clean_device、pyats_run_blitz、pyats_run_robot 内でも実行されます。

• 動的テストスクリプトは制限付きサンドボックスで実行されます（禁止インポート: os、sys、subprocess など）。

• pyats_clean_device は、デバイスを再起動・消去・再イメージ化する実際の Genie Clean ステージを実行することはありません — connect+execute_command のみが生成され、デフォルトは dry_run=True です。実際に実行するには正確な確認フレーズも必要です。

• すべてのプロセスグローバルキャッシュ（接続キャッシュ、テストベッドキャッシュ、設定/学習スナップショット、操作ログ）はロックで保護されているため、同時の HTTP クライアントが共有状態を破損することはありません。

• すべての認証情報は .env から取得されます — テストベッドファイルやソースコードに保存されることはありません。

プロジェクト構造

.
├── pyats_mcp_server.py      # MCP server
├── test_pyats_mcp_server.py # Unit tests (119 tests)
├── benchmark/               # Pre/post, stateful/stateless transport benchmark
├── Dockerfile               # Container definition
├── requirements.txt         # Pinned runtime dependencies
├── requirements-dev.txt     # Dev/test dependencies
├── pyproject.toml           # Tool config (black, isort, pytest, mypy)
├── .env.example             # Configuration template — copy to .env
├── .gitignore
├── LICENSE
└── CONTRIBUTING.md

開発

# Install dev dependencies with uv
uv venv .venv && uv pip install -r requirements-dev.txt

# Run tests
.venv/bin/python -m pytest

# Lint and format
.venv/bin/black .
.venv/bin/isort .
.venv/bin/flake8 . --max-line-length=100

完全なセットアップと PR ワークフローについては CONTRIBUTING.md を参照してください。

ベンチマーク

benchmark/ は、実際のテストベッドに対して、ステートフルモードとステートレスモードの両方で STDIO（レガシー）と Streamable HTTP を比較します。シナリオ一覧は benchmark/scenarios.py、比較レポートの作成は benchmark/aggregate.py を参照してください。benchmark/results/summary.md に最新の実行結果の数値があります。

ライセンス

MIT