Skip to main content
Glama
README.md
# PT-MCP — Claude ↔ Cisco Packet Tracer

An MCP server that lets Claude build Packet Tracer projects live: add devices,
cable them, push IOS configs, set PC IPs, and save `.pkt` files.

```
Claude ──stdio/MCP──> pt-mcp (Python) ──HTTP long-poll 127.0.0.1:54321──> bridge web view
                                                                              │ $se()
                                                    Packet Tracer IPC  <── Script Engine (main.js)
```

Packet Tracer has no external API. It does have **Script Modules**: JavaScript
running inside PT with full access to its IPC API (`ipc.network()`,
`ipc.appWindow()`, …). `packet_tracer/main.js` opens a small web view that polls
this server for jobs, runs each job in the Script Engine, and posts the result back.

Verified live on Packet Tracer **9.0.1** (Linux): devices, cabling, IOS config,
PC addressing, ping/ARP and saving `.pkt` all work end to end.

## 1. Install the server

```bash
git clone https://github.com/mohammed-w-mosabeh/packet-tracer-mcp.git
cd packet-tracer-mcp
uv sync
```

`.mcp.json` in this folder registers it with Claude Code as `packet-tracer`
(approve it the first time you start `claude` here). To use it from any folder:

```bash
claude mcp add packet-tracer -s user -- uv run --directory /path/to/packet-tracer-mcp pt-mcp
```

## 2. The bridge in Packet Tracer

It lives in `~/pt/extensions/ptmcp.pts`, is registered as a persistent script
module and starts with Packet Tracer. To reinstall from scratch:

1. **Extensions → Scripting → New PT Script Module**.
2. **General**: name `PT-MCP Bridge`, ID `com.ptmcp.bridge`, Startup **On Startup**,
   tick **all Security Privileges**.
3. **Script Engine** → **Import** `packet_tracer/main.js`.
4. **Custom Interfaces** → **Import** `packet_tracer/bridge.htm` (required: only
   pages served from the module get the `$se()` bridge to the script engine).
5. **Info** → **Export** to `~/pt/extensions/ptmcp.pts`, answer **Yes** to add it,
   then **Start**. (Dismiss the "saved in an earlier version" warning.)

Editors are read-only while the module runs: Stop → edit/Import → Info → Save → Start.

A small **"PT-MCP Bridge"** window shows **connected to MCP server** while Claude is
running; otherwise "waiting…", and it reconnects by itself.

### Quirks found while wiring it up

- `$se()` breaks on multi-line string args, so the server ships every job as a
  one-line `eval(decodeURIComponent('…'))`.
- Results are POSTed as `text/plain` to avoid a CORS preflight that QtWebEngine drops.
- `CiscoDevice.enterCommand(cmd, "")` reports everything as invalid; the server
  types into the device's `TerminalLine` instead and captures `outputWritten`.
- IOS `ping` output arrives asynchronously (simulation time runs after the call);
  check with `show arp` / a second command.

## 3. Use it

Ask Claude things like:

> Build a lab with a 2911 router, a 2960 switch and 3 PCs on 192.168.10.0/24,
> router as gateway, then save it to ~/pt/saves/lab1.pkt

## Tools

| Tool | What it does |
|---|---|
| `pt_status` | Is the bridge connected? |
| `pt_new_project` | New empty workspace (optional save) |
| `pt_list_models` | Device categories / exact model names |
| `pt_add_device`, `pt_remove_device`, `pt_rename_device`, `pt_move_device` | Devices |
| `pt_list_devices`, `pt_device_details` | Inspect devices and port names |
| `pt_connect`, `pt_disconnect`, `pt_list_links` | Cables |
| `pt_add_module` | Insert HWIC/NM modules (e.g. `HWIC-2T` serial) |
| `pt_cli`, `pt_show`, `pt_show_running_config` | IOS configuration on routers/switches |
| `pt_configure_host`, `pt_host_command` | PC/server IP settings, command prompt |
| `pt_set_power`, `pt_add_note` | Misc |
| `pt_save`, `pt_open` | Files |
| `pt_build_topology` | Whole lab in one call |
| `pt_run_js` | Raw JavaScript against the PT IPC API |

## Desktop helper (`tools/x`)

`tools/x` (`tools/xdesk.py`) is a small X11 screenshot/click/type tool used to set
up the bridge without a human. It only touches XWayland windows (Packet Tracer
runs under XWayland), needs no sudo, and pulls `python-xlib` + Pillow into an
isolated uv environment. `tools/ptdev.py` runs the bridge without an MCP client
for debugging (don't run it while Claude Code's server is up — same port).

## Notes

- Port `54321` is fixed in `packet_tracer/bridge.htm`; change both it and
  `PT_MCP_PORT` together if you need another one.
- The HTTP bridge only listens on `127.0.0.1`.
- IPC API reference ships with PT: `<PT>/help/default/IpcAPI/index.html`.

## License

[MIT](LICENSE)