pyATS MCP 서버

Cisco pyATS와 Genie는 이미 네트워크와 대화하는 방법을 알고 있습니다 — show 명령어 파싱, 설정 푸시, 기능 상태 학습, 선언적 테스트 실행. 하지만 AI 에이전트가 이 중 어떤 것도 직접 구동할 수 있는 방법은 없었습니다. 이 서버가 그 격차를 메웁니다: pyATS/Genie를 구조화되고 보호 장치가 있는 MCP 도구 세트로 감싸서, Claude 같은 에이전트가 실제 테스트베드에 대해 Model Context Protocol의 현재 Streamable HTTP 전송 방식을 통해 호출할 수 있게 합니다.

에이전트를 이 서버에 연결하면 장치 조회, show 명령어 실행 및 파싱, 롤백 지점이 있는 설정 적용, 변경 전후 기능 상태 학습 및 diff, 스레드 풀 또는 장치당 프로세스 하나로 플릿 전체에 명령어 팬아웃, 선언적 Blitz 또는 Robot Framework 테스트 실행, 장치의 REST/RESTCONF API 직접 호출까지 가능합니다. 모든 위험한 경로는 장치에 도달하기 전에 보호되며, 모든 호출은 에이전트가 세션 중간에 검토할 수 있는 인메모리 감사 로그에 기록됩니다.

한눈에 보기

• 전송 방식 — Streamable HTTP(mcp>=2.0.0), 상태 유지 또는 무상태, 환경 변수 하나로 선택. STDIO는 제거되었습니다.

• 26개 도구 — 디스커버리, show 명령어, 설정, Genie learn/diff, Genie Clean, 선언적 테스트(Blitz, Robot Framework, AEtest), 일반 REST/RESTCONF, Cisco XPresso 전반에 걸쳐 제공.

• 두 가지 팬아웃 방식 — 여러 장치에 명령어를 분산 실행하는 방법: 일상적인 사용을 위한 공유 스레드 풀, 또는 실제 규모에서 진정한 격리가 필요할 때 장치당 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

어느 쪽이든 서버는 한 번 시작하고 클라이언트가 연결하도록 하는 장기 실행 프로세스입니다 — 에이전트가 세션마다 생성하는 것이 아닙니다. 각 클라이언트가 연결하는 정확한 방법은 아래를 참조하세요.

에이전트 연결

서버는 한 가지를 노출합니다: 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 서버는 대신 Settings → Connectors의 Custom Connector로 추가되며, Desktop은 로컬 머신이 아닌 Anthropic의 클라우드에서 연결합니다 — 따라서 localhost가 아닌 실제 공개적으로 접근 가능한 HTTPS URL이 필요합니다.

어쨌든 자신의 머신에서 실행 중인 서버를 Desktop에 연결하려면 mcp-remote를 로컬 stdio 프록시로 통해 연결하세요:

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

Raw 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

• "R1과 R2에 대해 이 Blitz 테스트를 실행해" / "이 Robot Framework 스위트를 실행해" → pyats_run_blitz / pyats_run_robot

에이전트가 이를 스스로 연결합니다 — 결과를 설명하면 도구를 선택합니다.

사용 가능한 도구

기능별로 그룹화된 26개 도구.

디스커버리

Show 명령어

설정

상태 및 진단

테스트 및 자동화

API

세션

보안

• Show 명령어는 검증됩니다 — 파이프, 리다이렉트, 위험한 키워드는 차단됩니다.

• Config 변경 사항은 reload, erase, write erase, delete, format에 대해 검사됩니다 — 동일한 검사가 pyats_clean_device, pyats_run_blitz, pyats_run_robot 내부에서도 실행됩니다.

• 동적 테스트 스크립트는 제한된 샌드박스에서 실행됩니다 (금지된 import: os, sys, subprocess 등).

• pyats_clean_device는 장치를 재부팅, 삭제, 또는 재이미징하는 실제 Genie Clean 단계를 실행하지 않습니다 — connect+execute_command만 생성되며 — 기본값은 dry_run=True입니다; 실제 실행에는 정확한 확인 문구도 필요합니다.

• 모든 프로세스 전역 캐시(연결 캐시, testbed 캐시, config/learn 스냅샷, 작업 로그)는 잠금으로 보호되므로, 동시 HTTP 클라이언트가 공유 상태를 손상시킬 수 없습니다.

• 모든 자격 증명은 .env에서 가져옵니다 — testbed 파일이나 소스 코드에 저장되지 않습니다.

프로젝트 구조

.
├── 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/는 실제 testbed를 대상으로 상태 저장 및 무상태 모드 모두에서 STDIO(레거시)를 Streamable HTTP와 비교합니다. 시나리오 목록은 benchmark/scenarios.py, 비교 보고서 작성은 benchmark/aggregate.py를 참조하세요; benchmark/results/summary.md에는 가장 최근 실행 수치가 있습니다.

라이선스

MIT