pyATS_MCP

pyATS MCP Server



MCP server that wraps Cisco pyATS and Genie, letting AI agents (Claude, LangGraph, etc.) run show commands, apply configuration, and query network state over STDIO using JSON-RPC 2.0.

All communication is via STDIN/STDOUT — no HTTP ports, no REST endpoints.

---

Quick Start

# 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
python3 pyats_mcp_server.py

---

Configuration

All device details and credentials live in a .env file — nothing is hard-coded in the repo.

1. Copy the template

cp .env.example .env

2. Set the server variables

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

3. Add a block for each device

Every device in your testbed.yaml uses %ENV{VAR} substitution, so credentials and connection details are read from .env at runtime.

Use the {DEVICENAME}_{FIELD} naming convention:

# 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)

If a group of devices shares credentials you can define group-level vars and reference them across devices:

SITE_A_USERNAME=netops
SITE_A_PASSWORD=s3cr3t
SITE_A_ENABLE_PASSWORD=s3cr3t

4. Reference the variables 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

For devices with unknown OS, set os: "%ENV{DEVICE_OS}" with DEVICE_OS=generic in .env and optionally add learn_os: true under arguments: — Unicon will detect and cache the OS after the first connection.

---

Docker

Build

docker build -t pyats-mcp-server .

Run (pass .env directly)

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

MCP client config (Docker)

{
  "mcpServers": {
    "pyats": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/.env",
        "-v", "/absolute/path/to/testbed.yaml:/app/testbed.yaml",
        "pyats-mcp-server"
      ]
    }
  }
}

MCP client config (local Python)

{
  "mcpServers": {
    "pyats": {
      "command": "python3",
      "args": ["-u", "/path/to/pyats_mcp_server.py"],
      "env": {
        "PYATS_TESTBED_PATH": "/absolute/path/to/testbed.yaml"
      }
    }
  }
}

---

Available Tools

| Tool | Description | |------|-------------| | pyats_list_devices | List all devices in the testbed | | pyats_search_devices | Fuzzy-search devices by name or alias | | pyats_run_show_command | Run a validated show command; returns parsed JSON or raw output | | pyats_run_show_command_on_multiple_devices | Run a show command across multiple devices concurrently | | pyats_ping_from_network_device | Execute a ping from a network device | | pyats_run_linux_command | Run a command on a Linux host | | pyats_configure_device | Apply configuration commands with safety guardrails | | pyats_configure_devices_multi | Apply configuration across multiple devices concurrently | | pyats_configure_with_diff | Apply config and return a before/after diff | | pyats_rollback_config | Roll back to the last saved configuration snapshot | | pyats_device_health | Snapshot CPU, memory, interfaces, and routing state | | pyats_get_neighbors | Retrieve CDP/LLDP neighbors | | pyats_find_interface_by_ip | Find which interface owns a given IP address | | pyats_run_dynamic_test | Execute a sandboxed pyATS test script | | pyats_get_operation_log | Retrieve the in-memory operation log |

---

Security

• Show commands are validated — pipes, redirects, and dangerous keywords are blocked
• Config changes are checked for reload, erase, write erase, delete, format
• Dynamic test scripts run in a restricted sandbox (banned imports: os, sys, subprocess, etc.)
• All credentials come from .env — never stored in the testbed file or source code

---

Project Structure

.
├── pyats_mcp_server.py      # MCP server
├── test_pyats_mcp_server.py # Unit tests (85 tests)
├── 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

---

Development

# 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