packet-tracer-mcp

Servidor Model Context Protocol para controlar Cisco Packet Tracer 9.0 desde fuera. Una extensión propia se cuelga del editor de PT, abre un bridge HTTP local y desde ahí el servidor MCP llama a la API IPC nativa de PT para crear topologías, configurar routers, lanzar simulaciones, etc. Escrito en TypeScript sobre Bun.

[!WARNING] Proyecto experimental. Es la versión 0.1.0, hecha en mis ratos libres como experimento personal. Funciona contra PT 9.0.0.0810 en mi PC y pasa los smoke tests, pero no la consideres lista para producción. Espera bugs, cambios de API y cosas que se rompen al actualizar PT. Si te animas a probarla, abre issues con lo que veas.

_{Demo acelerada x15: el cliente MCP lanza una receta y el canvas de Packet Tracer 9 se va llenando solo (devices, cableado, configuración).}

Autor: Juan Cordero Pascual · Licencia: MIT Idiomas: español (este archivo) · English

---

Tabla de contenidos

• Por qué otro MCP de Packet Tracer
• Filosofía: canvas-first
• Requisitos
• Arranque rápido
  • Conectar un cliente MCP
  • Compilar a binario único
  • Tests
  • Recorrido end-to-end
• Capacidades
• Recetas incluidas
• Configuración
• Documentación
• FAQ
• Estructura del proyecto
• Estado

---

Por qué otro MCP de Packet Tracer

Los proyectos para PT 6.x–8.x se apoyaban en librerías JS cargadas por una extensión firmada de terceros. PT 9.0 cerró ese camino: los App Meta Files (.pta) ahora tienen que ir firmados con ECDSA por Cisco, así que ningún proyecto open-source puede entregar uno. La alternativa que queda es hablar con la webview de PT desde fuera, y eso es lo que hace este servidor:

• Hay una extensión .pts propia que se instala desde el menú Extensions de PT. Lo único que hace es arrancar un bucle de polling contra el bridge HTTP local.
• Cuando el servidor MCP necesita escribir, llama a la API IPC nativa de PT directamente: cosas como ipc.appWindow().getActiveWorkspace().getLogicalWorkspace().addDevice(...) o getDevice(...).getCommandLine().enterCommand(...). Sin librerías intermedias, sin JS opaco copiado de otros sitios.
• Todo el JS que termina ejecutándose en el Script Engine de PT lo genera este repo. Si quieres saber qué se está mandando, está en src/ipc/.

---

Filosofía: canvas-first

Otras herramientas mantienen un objeto "plan" en memoria, lo validan y al final lo vuelcan al simulador. Aquí no funciona así:

• No hay ningún TopologyPlan en memoria. Lo que hay en PT es lo que hay; el plan es el canvas.
• Cada receta vuelve a leer un snapshot del canvas antes de actuar. Si la lanzas dos veces sobre un canvas a medio construir, la segunda vez termina lo que faltaba en lugar de duplicar dispositivos. Sale idempotente sin tener que pensarlo.
• La validación se hace contra el canvas vivo, no contra una estructura interna. Cuando algo falla (IPs duplicadas, peers en subredes distintas, un router apagado) lo ves directamente en PT, no en un grafo abstracto.
• La persistencia guarda snapshots, no planes. Volver atrás significa comparar el canvas actual con un dump anterior y ver qué ha cambiado. No hay rehidratación mágica.

Si quieres el detalle, está en docs/ARCHITECTURE.md.

---

Requisitos

• Cisco Packet Tracer 9.0 (macOS, Windows o Linux).
• Bun >=1.2. Con Node solo no vale: el código es TypeScript y se ejecuta directamente con Bun, sin paso previo de compilación.
• La extensión mcp-bridge.pts instalada en PT. Viene en el repo en extension/dist/.

[!TIP] ¿Por qué Bun y no Node? Bun ejecuta .ts nativamente, arranca en milisegundos y trae fetch, HTTP y test runner de serie sin instalar dependencias. Si solo tienes Node, puedes instalar Bun con curl -fsSL https://bun.sh/install | bash (o brew install bun en macOS). Convive con Node sin pisarse.

---

Arranque rápido

git clone https://github.com/jcorderop02/packet-tracer-mcp.git
cd packet-tracer-mcp
bun install
bun run start              # streamable-HTTP en :39001 (default)
# o bien:
bun run src/index.ts --stdio   # modo stdio para clientes MCP que lo prefieran

En Packet Tracer 9:

1. Extensions > Scripting > Configure PT Script Modules > Add y selecciona extension/dist/mcp-bridge.pts.
2. Marca la extensión como activa.
3. Abre la ventana desde Extensions > MCP Bridge una vez por sesión.

El polling arranca solo en cuanto la ventana se carga. Para comprobar que todo está bien, lanza pt_bridge_status: en menos de un segundo debería responder connected: true.

El proceso completo de instalación está en docs/BOOTSTRAP.md.

El endpoint MCP queda en:

http://127.0.0.1:39001/mcp

[!NOTE] Por qué :39001. PT 9 ya tiene su propio IPC nativo (no documentado, con handshake firmado por Cisco) escuchando en :39000. Para no chocar y dejar claro que el servidor MCP es algo aparte, este escucha en :39001. Si te molesta, cámbialo con la variable de entorno PACKETTRACER_MCP_PORT.

Conectar un cliente MCP

<details> <summary><strong>Claude Code</strong> (CLI, recomendado)</summary>

Una sola línea, sin tocar JSON:

claude mcp add --transport http packet-tracer http://127.0.0.1:39001/mcp

Verifica con /mcp dentro de Claude Code: debe aparecer packet-tracer con sus 57 tools.

</details> <details> <summary><strong>Claude Desktop</strong></summary>

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu SO y reinicia Claude Desktop:

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

</details> <details> <summary><strong>Cursor</strong></summary>

Settings → MCP → Add new MCP server → pega la URL http://127.0.0.1:39001/mcp con transporte http.

</details> <details> <summary><strong>VS Code</strong> (Continue / Cline)</summary>

En el config.json del cliente:

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

</details> <details> <summary><strong>Gemini CLI</strong></summary>

Edita ~/.gemini/settings.json:

{
  "mcpServers": {
    "packet-tracer": {
      "httpUrl": "http://127.0.0.1:39001/mcp"
    }
  }
}

Verifica con /mcp list.

</details> <details> <summary><strong>Codex CLI</strong></summary>

Edita ~/.codex/config.toml:

[mcp_servers.packet-tracer]
url = "http://127.0.0.1:39001/mcp"

</details> <details> <summary><strong>Smoke con <code>curl</code></strong> (sin cliente)</summary>

Para confirmar que el server responde antes de configurar nada:

curl -sS -X POST http://127.0.0.1:39001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}'

Debe devolver un result con serverInfo.name = "packet-tracer-mcp". Un segundo POST con "method":"tools/list" devuelve las 57 tools con su inputSchema.

</details>

Compilar a binario único

bun run build
./dist/packet-tracer-mcp

Tests

bun test

La suite unitaria cubre la aritmética de subnetting, la inspección del canvas, el parser de snapshots, los diffs, la validación de blueprints y los builders CLI de cada receta. No hace falta PT corriendo para ejecutarla.

Recorrido end-to-end

Con el bridge conectado (pt_bridge_status → connected: true), una sesión completa más o menos se ve así:

1. pt_list_recipes                          # confirmar lo disponible
2. pt_forecast recipe='chain' params={routers:3, pcsPerLan:2}
                                            # estimación dry-run, ningún cambio
3. pt_cook_topology recipe='chain'
       params={routers:3, pcsPerLan:2, routing:'ospf'}
                                            # construye el lab; idempotente
4. pt_inspect_canvas                        # findings: IPs duplicadas, etc.
5. pt_explain_canvas                        # narración legible
6. pt_save_snapshot name='chain-baseline'   # captura T-0
7. pt_run_cli device='R1' command='show ip route'
                                            # comprobación rápida desde el CLI
8. pt_diff_snapshots before='chain-baseline'
                                            # qué ha cambiado desde T-0
9. pt_save_pkt path='/abs/path/lab.pkt'     # guardar como .pkt nativo

Si algo se ha torcido por el camino, pt_mend_canvas aplica reparaciones conservadoras (encender dispositivos que ya están cableados pero apagados, ese tipo de cosas) y avisa de lo que no se atreve a tocar.

---

Capacidades

packet-tracer-mcp expone 57 herramientas MCP agrupadas por dominio.

Bridge y diagnóstico

pt_bridge_status, pt_ping, pt_clear_canvas.

Catálogo y descubrimiento

pt_list_devices, pt_list_modules, pt_list_recipes, pt_list_snapshots, pt_get_device_details.

Inspección del workspace en vivo (read-only)

pt_query_topology, pt_inspect_canvas, pt_explain_canvas, pt_forecast (dry-run de receta), pt_generate_configs (genera el IOS CLI offline de una receta sin tocar PT — útil para documentación, aulas o reproducir el lab en hardware real), pt_inspect_ports (estado per-puerto: link/up/proto, MAC, IP/máscara, wireless), pt_read_vlans (base VLAN viva por switch), pt_read_acl (ACLs configuradas leídas vía AclProcess), pt_show_bgp_routes (parsea show ip bgp en filas estructuradas), pt_read_project_metadata (descripción/versión/filename del .pkt actual).

Edición primitiva del canvas

pt_add_device, pt_add_module, pt_create_link, pt_delete_device, pt_delete_link, pt_move_device, pt_auto_layout (recoloca todo el canvas en una rejilla por capas, detecta routers de tránsito y los baja a un segundo piso), pt_rename_device, pt_set_pc, pt_set_device_power (toggle Device.setPower idempotente), pt_add_canvas_annotation (notas/líneas/círculos), pt_manage_clusters (lista/elimina/disuelve clusters lógicos), pt_send_raw (vía de escape: ejecuta JS arbitrario en el Script Engine).

Edición a nivel de receta (orquestación)

`