pyATS MCP Server

Cisco pyATS und Genie wissen bereits, wie man mit einem Netzwerk spricht – Show-Befehle parsen, Konfiguration übertragen, Feature-Zustände lernen, deklarative Tests ausführen. Was ihnen fehlte, war eine Möglichkeit für einen KI-Agenten, all das direkt zu steuern. Dieser Server schließt diese Lücke: Er kapselt pyATS/Genie als eine Reihe strukturierter, abgesicherter MCP-Tools, die ein Agent wie Claude über den aktuellen Streamable-HTTP-Transport des Model Context Protocol gegen eine echte Testbed aufrufen kann.

Richten Sie einen Agenten darauf aus, und er kann ein Gerät nachschlagen, einen Show-Befehl ausführen und parsen, Konfiguration mit einem Rollback-Punkt anwenden, den Zustand einer Funktion vor und nach einer Änderung lernen und diffen, einen Befehl über eine Flotte verteilen – ein Thread-Pool oder ein Prozess pro Gerät – einen deklarativen Blitz- oder Robot-Framework-Test ausführen oder die REST/RESTCONF-API eines Geräts direkt aufrufen. Jeder riskante Pfad wird abgesichert, bevor er ein Gerät erreicht, und jeder Aufruf landet in einem In-Memory-Audit-Log, das der Agent mitten in der Sitzung einsehen kann.

Auf einen Blick

• Transport — Streamable HTTP (mcp>=2.0.0), zustandsbehaftet oder zustandslos, wählbar über eine Umgebungsvariable. STDIO ist weg.

• 26 Tools für Discovery, Show-Befehle, Konfiguration, Genie learn/diff, Genie Clean, deklaratives Testen (Blitz, Robot Framework, AEtest), generisches REST/RESTCONF und Cisco XPresso.

• Zwei Möglichkeiten, einen Befehl zu verteilen über viele Geräte – ein gemeinsamer Thread-Pool für den Alltag oder ein OS-Prozess pro Gerät (pyats.async_.pcall), wenn Sie echte Isolation im großen Maßstab wünschen.

• Schutzmechanismen statt Ehrensysteme – gefährliche Befehle werden blockiert, bevor sie ein Gerät erreichen, Genie Clean kann niemals eine Stufe ausführen, die ein Gerät neu startet oder neu aufspielt, und destruktive Aktionen erfordern eine exakte Bestätigungsphrase.

• Nichts ist fest verdrahtet – alle Anmeldedaten und Gerätedetails leben in .env und werden zur Laufzeit über %ENV{}-Substitution in testbed.yaml eingezogen.

Related MCP server: network-mcp

Voraussetzungen

• Python 3.10+

• Eine pyATS-testbed.yaml, die auf echte oder virtuelle Netzwerkgeräte zeigt – ein physisches Labor, Cisco Modeling Labs / VIRL / GNS3 oder alles andere, das Unicon über SSH/Telnet erreichen kann. pyATS MCP simuliert kein Netzwerk; es steuert eines.

• Einen MCP-fähigen Client, um mit ihm zu sprechen – siehe Verbinden Sie Ihren Agenten unten.

Schnellstart

# 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

Der MCP-Endpunkt ist dann unter http://<host>:<port>/mcp erreichbar.

Konfiguration

Alle Gerätedetails und Anmeldedaten leben in einer .env-Datei – nichts ist im Repository fest verdrahtet.

1. Kopieren Sie die Vorlage

cp .env.example .env

2. Legen Sie die Servervariablen fest

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 setzt stateless_http=True auf dem Streamable-HTTP-Transport, sodass kein serverseitiger Sitzungszustand zwischen Anfragen von Clients erhalten bleibt, die noch das ältere, handshake-basierte Protokoll aushandeln. Clients, die das aktuelle MCP-Protokoll (2026-07-28, SEP-2575) sprechen, sind unabhängig von dieser Einstellung standardmäßig handshake-frei – das kommt vom mcp>=2.0.0-SDK selbst, nicht von etwas, das hier konfiguriert ist.

3. Fügen Sie einen Block für jedes Gerät hinzu

Jedes Gerät in Ihrer testbed.yaml verwendet %ENV{VAR}-Substitution, sodass Anmeldedaten und Verbindungsdetails zur Laufzeit aus .env gelesen werden.

Verwenden Sie die Namenskonvention {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)

Wenn eine Gruppe von Geräten Anmeldedaten teilt, definieren Sie Variablen auf Gruppenebene und referenzieren Sie sie geräteübergreifend:

SITE_A_USERNAME=netops
SITE_A_PASSWORD=s3cr3t
SITE_A_ENABLE_PASSWORD=s3cr3t

4. Referenzieren Sie die Variablen in 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

Für Geräte mit unbekanntem OS setzen Sie os: "%ENV{DEVICE_OS}" mit DEVICE_OS=generic in .env und fügen Sie optional learn_os: true unter arguments: hinzu – Unicon erkennt und cached das OS nach der ersten Verbindung.

Docker

Build

docker build -t pyats-mcp-server .

Ausführen (.env direkt übergeben)

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

In beiden Fällen ist der Server ein langlebiger Prozess, den Sie einmal starten und auf den Sie Clients ausrichten – er ist nichts, was ein Agent pro Sitzung erzeugt. Siehe unten, wie genau sich jeder Client mit ihm verbindet.

Verbinden Sie Ihren Agenten

Der Server stellt genau eine Sache bereit: einen MCP-Endpunkt unter http://<host>:<port>/mcp (Streamable HTTP). Jeder Client unten braucht nur diese URL – kein command/args, kein lokaler Prozess, den der Client verwalten muss.

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"

Oder fügen Sie es direkt in .mcp.json (projektbezogen, ins Repository eingecheckt) oder ~/.claude.json (benutzerbezogen) ein:

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

VS Code (GitHub Copilot Chat)

Fügen Sie eine .vscode/mcp.json im Workspace hinzu (oder führen Sie MCP: Add Server aus der Befehlspalette aus):

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

OpenAI Codex CLI

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

Oder in ~/.codex/config.toml:

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

Claude Desktop

Das claude_desktop_config.json von Claude Desktop ist nur für stdio – ein url-Feld darin funktioniert nicht (das ist ein bekanntes Problem, kein unterstützter Weg). Remote-/HTTP-Server werden stattdessen als Custom Connector unter Einstellungen → Connectors hinzugefügt, und Desktop verbindet sich von der Anthropic-Cloud aus, nicht von Ihrem lokalen Rechner – es braucht also eine echte, öffentlich erreichbare HTTPS-URL, nicht localhost.

Um Desktop trotzdem auf einen Server auf Ihrem eigenen Rechner auszurichten, überbrücken Sie ihn über mcp-remote als lokalen stdio-Proxy:

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

Reines Python (LangGraph, benutzerdefinierte Agenten, alles andere)

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"},
            )

Was Sie es fragen können

Sobald Sie verbunden sind, sprechen Sie mit ihm, wie Sie mit jemandem sprechen würden, der das Netzwerk bereits kennt:

• "Welche Geräte sind in der Testbed?" → pyats_list_devices

• "Zeig mir die BGP-Zusammenfassung auf CORE1" → pyats_run_show_command, geparst in strukturiertes JSON

• "Erstelle einen Snapshot des OSPF-Zustands von CORE1, wende dann diese Konfiguration an und zeig mir, was sich geändert hat" → pyats_learn_feature (vorher) → pyats_configure_with_diff → pyats_learn_feature (nachher) → pyats_diff_learned_snapshots

• "Führe show ip interface brief auf jedem Switch aus" → pyats_run_show_command_multi (oder pyats_pcall_show_command für Prozess-pro-Gerät-Isolation im echten Maßstab)

• "Wenn diese Konfigurationsänderung etwas kaputt macht, rolle sie zurück" → pyats_rollback_config

• "Führe diesen Blitz-Test gegen R1 und R2 aus" / "Führe diese Robot-Framework-Suite aus" → pyats_run_blitz / pyats_run_robot

Der Agent verknüpft diese selbst – Sie beschreiben das Ergebnis, er wählt die Tools.

Verfügbare Tools

26 Tools, gruppiert nach ihrer Funktion.

Discovery

Show-Befehle

Konfiguration

Zustand & Diagnose

Testen & Automatisierung

APIs

Sitzung

Sicherheit

• Show-Befehle werden validiert — Pipes, Umleitungen und gefährliche Schlüsselwörter werden blockiert.

• Konfigurationsänderungen werden auf reload, erase, write erase, delete, format geprüft — dieselbe Prüfung läuft in pyats_clean_device, pyats_run_blitz und pyats_run_robot.

• Dynamische Testskripte laufen in einer eingeschränkten Sandbox (gesperrte Importe: os, sys, subprocess usw.).

• pyats_clean_device führt nie eine echte Genie-Clean-Phase aus, die ein Gerät neu startet, löscht oder neu abbildet — es werden nur connect+execute_command generiert — und standardmäßig gilt dry_run=True; für einen echten Lauf ist außerdem eine exakte Bestätigungsphrase erforderlich.

• Jeder prozessglobale Cache (Verbindungscache, Testbed-Cache, Konfigurations-/Learn-Snapshots, Betriebsprotokoll) ist durch eine Sperre geschützt, sodass gleichzeitige HTTP-Clients den gemeinsamen Zustand nicht beschädigen können.

• Alle Anmeldedaten stammen aus .env — niemals in der Testbed-Datei oder im Quellcode gespeichert.

Projektstruktur

.
├── 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

Entwicklung

# 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

Siehe CONTRIBUTING.md für die vollständige Einrichtung und den PR-Workflow.

Benchmark

benchmark/ vergleicht STDIO (Legacy) mit Streamable HTTP sowohl im zustandsbehafteten als auch im zustandslosen Modus gegen ein echtes Testbed. Siehe benchmark/scenarios.py für die Szenarioliste und benchmark/aggregate.py für die Erstellung des Vergleichsberichts; benchmark/results/summary.md enthält die Zahlen des letzten Laufs.

Lizenz

MIT