Packet Tracer MCP Server

Servidor MCP que permite a cualquier LLM (Copilot, Claude, etc.) crear, configurar, validar y desplegar topologías de red completas en Cisco Packet Tracer.

Le decís "creame una red con 3 routers, DHCP y OSPF" y el servidor planifica la topología, valida todo, genera los scripts y configs, y lo despliega directo en PT en tiempo real.

Python 3.11+ · Pydantic 2.0+ · FastMCP · Streamable HTTP

Instalación

Opción A: Usando pip (estándar)

git clone <repo>
cd MCP_Packet_Tracer
pip install -e .

Opción B: Usando uv (rápido)

git clone <repo>
cd MCP_Packet_Tracer
uv venv
uv pip install -e .

Nota: uv es un gestor de paquetes de Python más rápido. Para instalarlo:

curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/Mac

Uso

1. Levantar el servidor

Con pip (estándar):

python -m src.packet_tracer_mcp

Con uv (desde el entorno virtual):

# Activar el entorno virtual
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows
python -m src.packet_tracer_mcp

O directamente con uv run:

uv run python -m src.packet_tracer_mcp

Esto inicia:

Servidor MCP en http://127.0.0.1:39000/mcp (streamable-http)
Bridge HTTP en http://127.0.0.1:54321 (comunicación con Packet Tracer)

Ambos arrancan automáticamente. No se necesita ningún script adicional.

Para modo stdio (debug/legacy): python -m src.packet_tracer_mcp --stdio

2. Configurar el cliente MCP

VS Code — .vscode/mcp.json:

{
  "servers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}

Claude CLI — ~/.claude.json:

{
  "mcpServers": {
    "packet-tracer": {
      "type": "http",
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}

3. Usar desde el LLM

Pedile al LLM que cree una red. El servidor expone 22 tools MCP que cubren todo el pipeline:

Tool	Qué hace
`pt_list_devices`	Catálogo de dispositivos disponibles
`pt_list_templates`	Templates de topologías predefinidas
`pt_get_device_details`	Detalle de puertos/interfaces de un modelo
`pt_estimate_plan`	Estimación rápida sin generar plan completo
`pt_plan_topology`	Genera un plan completo (dispositivos, links, IPs, DHCP, rutas)
`pt_validate_plan`	Valida que el plan sea correcto
`pt_fix_plan`	Auto-corrige errores comunes
`pt_explain_plan`	Explicación en lenguaje natural del plan
`pt_generate_script`	Genera script JavaScript para PTBuilder
`pt_generate_configs`	Genera configuraciones CLI por dispositivo
`pt_full_build`	Pipeline completo de una sola vez
`pt_deploy`	Copia script al portapapeles con instrucciones
`pt_live_deploy`	Envía comandos directo a PT en tiempo real
`pt_bridge_status`	Verifica conexión con PT
`pt_query_topology`	Consulta dispositivos existentes en PT
`pt_delete_device`	Elimina un dispositivo de PT
`pt_rename_device`	Renombra un dispositivo en PT
`pt_move_device`	Mueve un dispositivo en el canvas
`pt_delete_link`	Elimina un enlace de PT
`pt_send_raw`	Envía JS arbitrario a PT
`pt_export`	Exporta plan + scripts + configs a archivos
`pt_list_projects` / `pt_load_project`	Gestión de proyectos guardados

¿Por qué el servidor corre en el puerto 39000?

El servidor MCP usa streamable-http en lugar de stdio. Esto significa que el servidor se levanta una vez como un proceso HTTP persistente y los clientes MCP se conectan a él por red.

Ventajas sobre stdio:

Persistencia — el servidor queda corriendo, no se reinicia con cada sesión del editor
Múltiples clientes — podés conectar VS Code, Claude Desktop u otros clientes al mismo servidor simultáneamente
Estado compartido — el bridge HTTP hacia Packet Tracer se mantiene activo entre requests
Debug más fácil — podés hacer curl al servidor, ver logs en la terminal donde corre
Desacoplamiento — el servidor no depende del ciclo de vida del editor

El puerto 39000 fue elegido para no colisionar con puertos comunes (3000, 5000, 8000, 8080) ni con el bridge interno de PT que usa el 54321.

Live Deploy — Despliegue en tiempo real

La feature principal: enviar comandos directamente a Packet Tracer sin copiar/pegar nada.

┌─────────┐         ┌──────────────┐   HTTP    ┌──────────────┐  $se()  ┌──────────────┐
│   LLM   │  MCP    │  MCP Server  │  :54321   │  PTBuilder   │  IPC   │ Packet Tracer│
│(Copilot)│ ──────► │  (:39000)    │ ────────► │  (WebView)   │ ─────► │   (Engine)   │
└─────────┘         └──────────────┘           └──────────────┘        └──────────────┘

Hay dos servidores HTTP corriendo:

Puerto	Qué es	Para qué
39000	Servidor MCP (streamable-http)	Recibe requests de tools del LLM/editor
54321	Bridge HTTP interno	Envía comandos JS a PTBuilder dentro de Packet Tracer

Setup del bridge (una vez por sesión de PT):

Abrí Packet Tracer 8.2+
Abrí Builder Code Editor (Extensions > Builder Code Editor)
Pegá este bootstrap y hacé clic en Run:

/* PT-MCP Bridge */ window.webview.evaluateJavaScriptAsync("setInterval(function(){var x=new XMLHttpRequest();x.open('GET','http://127.0.0.1:54321/next',true);x.onload=function(){if(x.status===200&&x.responseText){$se('runCode',x.responseText)}};x.onerror=function(){};x.send()},500)");

Eso hace que PTBuilder haga polling cada 500ms al bridge. Cuando el LLM genera comandos, el MCP Server los encola en el bridge y PT los ejecuta en tiempo real.

Arquitectura

src/packet_tracer_mcp/
├── adapters/mcp/          # Tools y resources MCP
├── application/           # Use cases + DTOs
├── domain/
│   ├── models/           # TopologyPlan, DevicePlan, LinkPlan
│   ├── services/         # Orchestrator, IPPlanner, Validator, AutoFixer
│   └── rules/            # Reglas de validación
├── infrastructure/
│   ├── catalog/          # Catálogo de dispositivos, cables, templates
│   ├── generator/        # Generador de scripts JS + configs CLI
│   ├── execution/        # Bridge HTTP + Live Executor
│   └── persistence/      # Proyectos guardados
├── server.py             # Entry point del servidor
└── settings.py           # Configuración

Flujo de datos

Request → el LLM describe qué red quiere
Planificación → el Orchestrator genera un TopologyPlan completo
Validación → el Validator verifica modelos, puertos, cables, IPs
Auto-fix → el AutoFixer corrige errores comunes automáticamente
Generación → se produce el script JS para PTBuilder + configs CLI
Deploy → se envía a PT vía bridge HTTP o se exporta a archivos

Direccionamiento IP

LANs: 192.168.X.0/24 — gateway en .1, PCs desde .2
Links inter-router: 10.0.X.0/30 — 2 hosts por enlace

Routing soportado

static — genera ip route completas
ospf — genera router ospf con áreas
none — sin routing

Tests

python -m pytest tests/ -v

Requisitos

Python 3.11+
Cisco Packet Tracer 8.2+ (para live deploy)
PTBuilder extension instalada en PT (incluida en PTBuilder/)

Listo. El MCP server puede crear dispositivos, enlaces y configurar routers automáticamente.

Nota técnica: El bootstrap inyecta un setInterval en el webview que hace polling HTTP. El $se('runCode', ...) bridgea del webview al Script Engine de PT. PTBuilder usa executeCode() que internamente hace code.replace(/\n/g, ""), por eso el bootstrap usa /* */ comments en vez de //.

Setup permanente (opcional):

Para que el polling arranque automáticamente al abrir Builder Code Editor:

En PT: Extensions > Scripting Interface
Seleccioná el módulo Builder
Reemplazá main.js e interface.js con las versiones modificadas en PTBuilder/source/
Guardá y reiniciá el módulo

MCP Tools (22)

Consulta

Tool	Descripción
`pt_list_devices`	Lista todos los dispositivos disponibles con sus puertos
`pt_list_templates`	Lista las plantillas de topología disponibles
`pt_get_device_details`	Detalles completos de un modelo específico

Estimación

Tool	Descripción
`pt_estimate_plan`	Dry-run: estima dispositivos, enlaces y complejidad sin generar

Planificación

Tool	Descripción
`pt_plan_topology`	Genera un plan completo desde parámetros (routers, PCs, routing, etc.)

Validación

Tool	Descripción
`pt_validate_plan`	Valida un plan con 15 tipos de error tipificados
`pt_fix_plan`	Auto-corrige errores comunes (cables, modelos, puertos)
`pt_explain_plan`	Genera explicación en lenguaje natural de cada decisión

Generación

Tool	Descripción
`pt_generate_script`	Genera script JavaScript para PTBuilder
`pt_generate_configs`	Genera configuraciones CLI (IOS) por dispositivo

Pipeline completo

Tool	Descripción
`pt_full_build`	Todo en uno: planifica, valida, genera y exporta

Despliegue en vivo

Tool	Descripción
`pt_deploy`	Copia script al portapapeles + instrucciones manuales
`pt_live_deploy`	Envía comandos directo a PT en tiempo real via HTTP bridge
`pt_bridge_status`	Verifica si el bridge está activo y PT está conectado

Interacción con topología existente

Tool	Descripción
`pt_query_topology`	Consulta qué dispositivos existen actualmente en PT
`pt_delete_device`	Elimina un dispositivo y sus enlaces de PT
`pt_rename_device`	Renombra un dispositivo en la topología activa
`pt_move_device`	Mueve un dispositivo a nuevas coordenadas en el canvas
`pt_delete_link`	Elimina el enlace de una interfaz específica
`pt_send_raw`	Envía código JS arbitrario al Script Engine de PT

Exportación y proyectos

Tool	Descripción
`pt_export`	Exporta a archivos (JS script, CLI configs, JSON plan)
`pt_list_projects`	Lista proyectos guardados
`pt_load_project`	Carga un proyecto guardado

MCP Resources (5)

URI	Descripción
`pt://catalog/devices`	Todos los dispositivos con puertos
`pt://catalog/cables`	Tipos de cable
`pt://catalog/aliases`	Aliases de modelos
`pt://catalog/templates`	Plantillas de topología
`pt://capabilities`	Capacidades del servidor

Dispositivos soportados

Routers

Modelo	Puertos
1941	Gig0/0, Gig0/1, Se0/0/0, Se0/0/1
2901	Gig0/0, Gig0/1, Se0/0/0, Se0/0/1
2911	Gig0/0, Gig0/1, Gig0/2, Se0/0/0, Se0/0/1
4321 (ISR4321)	Gig0/0/0, Gig0/0/1

Switches

Modelo	Puertos
2960-24TT	Fa0/1–24, Gig0/1–2
3560-24PS	Fa0/1–24, Gig0/1–2

End Devices

Modelo	Puertos
PC-PT	Fa0
Server-PT	Fa0
Laptop-PT	Fa0

Otros

Modelo	Tipo
Cloud-PT	WAN Cloud
AccessPoint-PT	Wireless AP

Tipos de cable

Cable	Uso típico
straight	Switch↔Router, Switch↔PC
cross	Router↔Router, Switch↔Switch, PC↔PC
serial	Router Serial↔Router Serial (WAN)
fiber	Conexiones de fibra óptica
auto	Detección automática

Direccionamiento IP

LANs: 192.168.X.0/24 — Gateway en .1, PCs desde .2
Inter-router links: 10.0.X.0/30 — Punto a punto entre routers
DHCP: Pool automático por LAN con exclusión del gateway

Routing soportado

Protocolo	Estado	Genera
static	✅ Completo	`ip route` commands
ospf	✅ Completo	`router ospf` configs
eigrp	🔲 Enum only	No implementado
rip	🔲 Enum only	No implementado
none	✅	Sin routing

Templates

Template	Descripción
`single_lan`	1 router + 1 switch + PCs
`multi_lan`	N routers interconectados, cada uno con su LAN
`multi_lan_wan`	Multi LAN con nube WAN
`star`	Router central con routers satelitales
`hub_spoke`	Hub-and-spoke
`branch_office`	Sucursales
`router_on_a_stick`	Inter-VLAN routing
`three_router_triangle`	3 routers en triángulo
`custom`	Personalizado

Arquitectura

src/packet_tracer_mcp/
├── adapters/mcp/              # MCP protocol layer
│   ├── tool_registry.py       # 22 MCP tools
│   └── resource_registry.py   # 5 MCP resources
├── application/               # Use cases + DTOs (requests/responses)
├── domain/                    # Core business logic
│   ├── models/               # TopologyPlan, DevicePlan, LinkPlan, errors
│   ├── services/             # Orchestrator, IPPlanner, Validator, AutoFixer
│   └── rules/                # Validation rules (devices, cables, IPs)
├── infrastructure/
│   ├── catalog/              # Device catalog, cables, templates, aliases
│   ├── generator/            # PTBuilder JS + CLI config generators
│   ├── execution/            # Executors + HTTP bridge
│   │   ├── live_bridge.py    # PTCommandBridge (HTTP server :54321)
│   │   ├── live_executor.py  # LiveExecutor (sends plan → bridge → PT)
│   │   ├── deploy_executor.py# DeployExecutor (clipboard + instructions)
│   │   └── manual_executor.py# ManualExecutor (file export)
│   └── persistence/          # Project save/load
├── shared/                    # Enums, constants, utilities
├── server.py                  # MCP server entry point
└── settings.py                # Version + config

Flujo de datos

TopologyRequest → Orchestrator → IPPlanner → Validator → AutoFixer
                                                            ↓
                                              TopologyPlan (validated)
                                                            ↓
                                    ┌───────────────────────┼──────────────────┐
                                    ↓                       ↓                  ↓
                            PTBuilder Script          CLI Configs        Live Deploy
                           (addDevice/addLink)    (hostname, IPs,     (HTTP bridge
                                                   DHCP, routing)      → PT real-time)

PTBuilder (extensión de PT)

El directorio PTBuilder/ contiene el código fuente del Script Module "Builder Code Editor":

Archivo	Función
`source/main.js`	Entry point — crea menú y webview
`source/runcode.js`	`runCode(scriptText)` — ejecuta JS en Script Engine
`source/userfunctions.js`	`addDevice()`, `addLink()`, `configureIosDevice()`, `configurePcIp()`, `queryTopology()`, `deleteDevice()`, `renameDevice()`, `moveDevice()`, `deleteLink()`
`source/devices.js`	Mapeo modelo → tipo numérico de PT
`source/links.js`	Mapeo tipo de cable → ID numérico
`source/modules.js`	Mapeo módulos de hardware
`source/window.js`	Gestión de la ventana webview (QWebEngine)
`source/interface/`	HTML + JS del editor web (status panel + real-time logging)
`Builder.pts`	Paquete compilado de la extensión (binario, no editable)

API principal de PTBuilder

// Crear dispositivo en coordenadas (x, y)
addDevice("R1", "2911", 100, 200);

// Crear enlace entre dos dispositivos
addLink("R1", "GigabitEthernet0/1", "S1", "GigabitEthernet0/1", "straight");

// Configurar router/switch con CLI commands
configureIosDevice("R1", "enable\nconfigure terminal\nhostname R1\ninterface GigabitEthernet0/0\nip address 192.168.0.1 255.255.255.0\nno shutdown\nexit");

// Configurar IP estática de PC
configurePcIp("PC1", false, "192.168.0.2", "255.255.255.0", "192.168.0.1");

// Configurar PC para DHCP
configurePcIp("PC1", true);

Tests

# Todos los tests
python -m pytest tests/ -v

# Un archivo
python -m pytest tests/test_full_build.py -v

# Un test específico
python -m pytest tests/test_full_build.py::TestFullBuild::test_basic_2_routers -v

34 tests cubriendo: IP planning, validación, auto-fix, explicación, estimación, generación y full build integration.

Ejemplo de uso rápido

Usuario:  "Creame una red con 2 routers, 2 switches, 4 PCs, DHCP y static routing"

→ pt_full_build genera:
  - 8 dispositivos: R1, R2, SW1, SW2, PC1, PC2, PC3, PC4
  - 7 enlaces: R1↔R2 (cross), R1↔SW1 (straight), R2↔SW2 (straight), SW1↔PC1, SW1↔PC2, SW2↔PC3, SW2↔PC4
  - IPs: LAN1 192.168.0.0/24, LAN2 192.168.1.0/24, Inter-router 10.0.0.0/30
  - DHCP pools en R1 y R2
  - Static routes bidireccionales
  - 23 comandos JavaScript enviados a PT

→ pt_live_deploy envía todo a Packet Tracer y aparecen los dispositivos configurados

Name		Name	Last commit message	Last commit date
.codex		.codex
.vscode		.vscode
PTBuilder		PTBuilder
src		src
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
README.md		README.md
SETUP-GUIDE.md		SETUP-GUIDE.md
WIKI.md		WIKI.md
pyproject.toml		pyproject.toml
test_bridge_functions.py		test_bridge_functions.py

Latest commit

History

Folders and files

Repository files navigation

Packet Tracer MCP Server

Instalación

Opción A: Usando pip (estándar)

Opción B: Usando uv (rápido)

Uso

1. Levantar el servidor

2. Configurar el cliente MCP

3. Usar desde el LLM

¿Por qué el servidor corre en el puerto 39000?

Live Deploy — Despliegue en tiempo real

Setup del bridge (una vez por sesión de PT):

Arquitectura

Flujo de datos

Direccionamiento IP

Routing soportado

Tests

Requisitos

Setup permanente (opcional):

MCP Tools (22)

Consulta

Estimación

Planificación

Validación

Generación

Pipeline completo

Despliegue en vivo

Interacción con topología existente

Exportación y proyectos

MCP Resources (5)

Dispositivos soportados

Routers

Switches

End Devices

Otros

Tipos de cable

Direccionamiento IP

Routing soportado

Templates

Arquitectura

Flujo de datos

PTBuilder (extensión de PT)

API principal de PTBuilder

Tests

Ejemplo de uso rápido

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages