pyATS MCP Server
This project implements a Model Context Protocol (MCP) Server that wraps Cisco pyATS and Genie functionality. It enables structured, model-driven interaction with network devices over STDIO using the JSON-RPC 2.0 protocol.
🚨 This server does not use HTTP or SSE. All communication is done via STDIN/STDOUT (standard input/output), making it ideal for secure, embedded, containerized, or LangGraph-based tool integrations.
🔧 What It Does
Connects to Cisco IOS/NX-OS devices defined in a pyATS testbed
Supports safe execution of validated CLI commands (show, ping)
Allows controlled configuration changes
Returns structured (parsed) or raw output
Exposes a set of well-defined tools via tools/discover and tools/call
Operates entirely via STDIO for minimal surface area and maximum portability
🚀 Usage
- Set your testbed path
export PYATS_TESTBED_PATH=/absolute/path/to/testbed.yaml
- Run the server
Continuous STDIO Mode (default)
python3 pyats_mcp_server.py
Launches a long-running process that reads JSON-RPC requests from stdin and writes responses to stdout.
One-Shot Mode
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/discover"}' | python3 pyats_mcp_server.py --oneshot
Processes a single JSON-RPC request and exits.
📦 Docker Support
Build the container
docker build -t pyats-mcp-server .
Run the container (STDIO Mode)
docker run -i --rm \
-e PYATS_TESTBED_PATH=/app/testbed.yaml \
-v /your/testbed/folder:/app \
pyats-mcp-server
🧠 Available MCP Tools
Tool Description
run_show_command Executes show commands safely with optional parsing
run_ping_command Executes ping tests and returns parsed or raw results
apply_configuration Applies safe configuration commands (multi-line supported)
learn_config Fetches running config (show run brief)
learn_logging Fetches system logs (show logging last 250)
All inputs are validated using Pydantic schemas for safety and consistency.
🤖 LangGraph Integration
Add the MCP server as a tool node in your LangGraph pipeline like so:
("pyats-mcp", ["python3", "pyats_mcp_server.py", "--oneshot"], "tools/discover", "tools/call")
Name: pyats-mcp
Command: python3 pyats_mcp_server.py --oneshot
Discover Method: tools/discover
Call Method: tools/call
STDIO-based communication ensures tight integration with LangGraph’s tool invocation model without opening HTTP ports or exposing REST endpoints.
📜 Example Requests
Discover Tools
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/discover"
}
Run Show Command
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "run_show_command",
"arguments": {
"device_name": "router1",
"command": "show ip interface brief"
}
}
}
🔒 Security Features
Input validation using Pydantic
Blocks unsafe commands like erase, reload, write
Prevents pipe/redirect abuse (e.g., | include, >, copy, etc.)
Gracefully handles parsing fallbacks and errors
📁 Project Structure
.
├── pyats_mcp_server.py # MCP server with JSON-RPC and pyATS integration
├── Dockerfile # Docker container definition
├── testbed.yaml # pyATS testbed (user-provided)
└── README.md # This file
📥 MCP Server Config Example (pyATS MCP via Docker)
To run the pyATS MCP Server as a container with STDIO integration, configure your mcpServers like this:
{
"mcpServers": {
"pyats": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PYATS_TESTBED_PATH",
"-v",
"/absolute/path/to/testbed/folder:/app",
"pyats-mcp-server"
],
"env": {
"PYATS_TESTBED_PATH": "/app/testbed.yaml"
}
}
}
}
{
"servers": {
"pyats": {
"type": "stdio",
"command": "python3",
"args": [
"-u",
"/Users/johncapobianco/pyATS_MCP/pyats_mcp_server.py"
],
"env": {
"PYATS_TESTBED_PATH": "/Users/johncapobianco/pyATS_MCP/testbed.yaml"
}
}
}
🧾 Explanation: command: Uses Docker to launch the containerized pyATS MCP server
args:
-i: Keeps STDIN open for communication
--rm: Automatically removes the container after execution
-e: Injects the environment variable PYATS_TESTBED_PATH
-v: Mounts your local testbed directory into the container
pyats-mcp-server: Name of the Docker image
env:
Sets the path to the testbed file inside the container (/app/testbed.yaml)
✍️ Author
John Capobianco
Product Marketing Evangelist, Selector AI
Author, Automate Your Network
Let me know if you’d like to add:
A sample LangGraph graph config
Companion client script
CI/CD integration (e.g., GitHub Actions)
Happy to help!