Packet Tracer MCP

MCP server that lets Claude Code build and configure topologies in Cisco Packet Tracer by speaking natural language: create devices, cable them, apply IOS commands, VLANs, OSPF, NAT, ACLs, VoIP, or reproduce an entire network from a diagram image.

Tu -> Claude Code --stdio--> mcp_server.py --HTTP--> bridge :54321
                                                         |
                              Packet Tracer  <-----------+
                              modulo Builder:
                                bridge.js         (pagina: hace el polling)
                                bridge_runner.js  (motor: ejecuta y devuelve)

The HTTP bridge runs inside the MCP server: no separate terminal is needed to start it. And the polling loop lives inside the Builder module: nothing needs to be pasted into Packet Tracer either.

Requirements

Related MCP server: packet-tracer-mcp

Getting started (one time only)

1. Dependencies

uv sync

2. Install the Builder module in Packet Tracer

packet_tracer/Builder.pts is the script module that defines inside PT the functions this project uses (addDevice, addLink, addModule, configureIosDevice, configurePcIp, getDevices, removeLink, addLabel, saveTopology) and the bridge that connects it to the HTTP server. Without this module nothing works.

In Packet Tracer (English menus, verified on PT 9.0.0):

1. Extensions -> Scripting -> Configure PT Script Modules

2. Add -> select packet_tracer/Builder.pts from this repo

3. Select Builder in the list -> Settings -> check On Startup, so the module starts on its own every time you open PT

4. To confirm it is running: the Builder Code Editor entry must appear in the Extensions menu. If it does not appear, the module did not start.

On startup, the module opens the Builder Code Editor window on its own. That window hosts the polling loop, so it must stay open while you work; if its title says "bridge activo", the bridge is working.

3. Open the project in Claude Code

From a terminal, in the project folder:

claude

Claude Code reads .mcp.json and starts the MCP server (and with it, the HTTP bridge) automatically. The first time it may ask you to confirm that you trust the folder.

To check that the server is connected, type /mcp inside Claude Code: packet-tracer should appear with its tools.

Daily use

1. Abre Packet Tracer
   -> la ventana "Builder Code Editor" se abre sola y debe quedarse abierta

2. En una terminal, en la carpeta del proyecto:
      cd ruta/al/pt_MCP
      claude

3. Dentro de Claude Code:
      /pt-iniciar     -> confirma que las 3 piezas responden

Nothing else needs to be started: not main.py, no pasting scripts into Packet Tracer, no extra terminals.

And from there, in natural language:

• "Create two 2911 routers connected by serial with 10.0.0.0/30 and one PC on each LAN"

• /pt-desde-imagen diagramas/ejemplo-red1.jpeg — reproduce the topology from a diagram

• "Configure VLAN 10 VENTAS on SW1 and put ports 1-4 in access"

If something does not appear on the canvas, ask Claude to call verificar_entorno(): it tells you which of the three pieces is down and how to bring it back up.

Structure

The two .js files in packet_tracer/ are already inside Builder.pts; they are loose in the repo so they can be read, versioned, and re-imported if needed.

uv run python main.py still works to start the bridge on its own, without MCP (that is what those debugging scripts need).

How a command travels

1. Claude calls an MCP tool, which translates it into a line of PT JS.

2. mcp_server.py queues it with POST /add_command.

3. bridge.js, inside the Builder Code Editor window, picks it up with GET /next_command (every 2 s) and calls $se('runCodeBridge', codigo).

4. bridge_runner.js runs it in the script engine and, if it returns a value, hands it back to the page with evaluateJavaScriptAsync.

5. The page publishes it with POST /command_result and mcp_server.py picks it up.

Step 4 is necessary because $se() only confirms that it dispatched the call (resolves to true), it never returns the value of the executed code.

Each request travels wrapped in a unique tag (a1b2c3d4|...) and only the result that carries it back is accepted. Without that, a late response stays in the queue and the next request picks up the wrong response.

Known limitations

• Packet Tracer does not expose the output of IOS commands: hacer_ping() and obtener_tabla_routing() send the command, but its output is only visible in the device console inside PT. API queries (getDevices(), port status) do return data.

• crear_dispositivo(), conectar_dispositivos(), agregar_modulo_router() and eliminar_conexion() confirm the actual result ([OK] / [ERROR]). The rest of the write commands (IOS configuration) are queued without confirmation: Exito: Comando enviado means queued, not executed.

• When creating certain devices, PT automatically adds a Power Distribution Device0 to the canvas. It shows up in inventories and is not an error.

• obtener_puertos_dispositivo() reads the device's actual ports in PT, including those on installed cards, and reports which ones are free.

• diagnosticar_red() does not see 802.1Q subinterfaces, VLANs, or routing tables: it reporting no failures does not guarantee connectivity.

• The Builder Code Editor window must stay open: that is where the loop lives.