Packet Tracer MCP Server
Tell your AI "create a network with 3 routers, OSPF and DHCP" - it plans, validates, generates, and deploys the topology directly into Cisco Packet Tracer in real time.
Showcase
Table of Contents
- What It Does
- Installation
- Quick Start
- How It Works
- MCP Tools (71)
- MCP Resources (5)
- Live Deploy Setup
- Supported Devices (74)
- Cable Types (15)
- Expansion Modules (150)
- IP Addressing
- Routing Protocols
- Topology Templates
- Architecture
- Testing
- Requirements
- Configuration
- Troubleshooting
- Offline Tools
◈ What It Does
A Model Context Protocol (MCP) server that gives any MCP-capable LLM client (GitHub Copilot, Claude Code, Claude Desktop, Codex CLI, Cursor) full programmatic control over Cisco Packet Tracer. 71 MCP tools and 5 MCP resources cover the complete workflow:
Natural language prompt
|
LLM (GitHub Copilot / Claude)
| MCP tools
Packet Tracer MCP Server (:39000)
| HTTP bridge
PTBuilder in Packet Tracer (:54321)
| Script Engine
Cisco Packet Tracer
-- devices created
-- cables connected
-- IOS configs applied
Key capabilities:
◈ Installation
git clone https://github.com/mex-i/MCP-Packet-Tracer
cd MCP-Packet-Tracer
pip install -e .
Cross-platform. The server and tools run identically on Windows, macOS and Linux — same commands, same output. Clipboard deploy automatically uses the native tool per OS (
clipon Windows,pbcopyon macOS,wl-copy/xclip/xselon Linux) and falls back to file export when none is present; generated scripts/configs are written with normalized (LF) line endings everywhere.
Optional — offline
.pkttools. To also use the Offline Tools for.pkt/.pkafiles, install the extra (pulls intwofish):pip install -e ".[offline]"
◈ Quick Start
After running pip install -e . (see Installation) the module packet_tracer_mcp is importable from any directory. That means python -m packet_tracer_mcp --stdio works from anywhere - no need to cd into the repo, no need to keep a server running in background. Most clients below use this stdio entry point and auto-launch the server on demand.
Two transport modes:
- stdio (recommended for desktop clients): the client spawns the server as a child process. Zero manual steps, works from any directory. The internal HTTP bridge to Packet Tracer (
:54321) still starts automatically inside the spawned process - live deploy works the same.- streamable-http (
http://127.0.0.1:39000/mcp): you start the server yourself withpython -m packet_tracer_mcpand multiple clients can share the same instance. Useful for VS Code multi-window setups or remote/shared scenarios.
1 — Connect your MCP client
Pick your client. All examples assume you already ran pip install -e ..
claude mcp add --scope user --transport stdio packet-tracer -- python -m packet_tracer_mcp --stdio
--scope userregisters the server in your global~/.claude.json, so it's available from any directory you launchclaudein (not tied to a single project).- The
--separator passes everything after it to the spawned process verbatim.
Verify:
claude mcp list
# packet-tracer: python -m packet_tracer_mcp --stdio - ✓ Connected
To remove later:
claude mcp remove packet-tracer --scope user
The config path depends on how Claude Desktop was installed. This matters on Windows because the Microsoft Store version sandboxes AppData and the official docs only mention the standard path.
How to tell which install you have on Windows: run
Get-Process claude \| Select-Object -ExpandProperty Pathin PowerShell. If the path containsWindowsApps\Claude_*, you have MSIX - use the second row above. Otherwise use the first.
Add (or merge into the existing file):
{
"mcpServers": {
"packet-tracer": {
"command": "python",
"args": ["-m", "packet_tracer_mcp", "--stdio"]
}
}
}
After saving, fully quit Claude Desktop and reopen - closing the window is not enough if "run in background" is on. On Windows: right-click the tray icon -> Quit, or run Get-Process claude | Stop-Process -Force.
Windows / MSIX gotcha: the sandbox may not expose
pythonon PATH. If the MCP indicator never lights up, replace"python"with the absolute path to your interpreter:"command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\Python\\Python312\\python.exe"Find your interpreter with
where.exe python(PowerShell) orwhich python(bash/zsh). Logs are at<config-dir>\logs\mcp-server-packet-tracer.log.
OpenAI Codex CLI uses TOML, not JSON. Open ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml) and append:
[mcp_servers.packet-tracer]
command = "python"
args = ["-m", "packet_tracer_mcp", "--stdio"]
Restart your codex session. Codex picks up MCP servers on launch.
Two options. stdio is the simplest - VS Code spawns the server when needed:
{
"servers": {
"packet-tracer": {
"type": "stdio",
"command": "python",
"args": ["-m", "packet_tracer_mcp", "--stdio"]
}
}
}
streamable-http if you want to keep one server running outside VS Code (e.g. shared across multiple windows):
{
"servers": {
"packet-tracer": {
"url": "http://127.0.0.1:39000/mcp"
}
}
}
For HTTP, start the server first in any terminal: python -m packet_tracer_mcp. Default endpoint is http://127.0.0.1:39000/mcp and the bridge runs at :54321.
Per-user (global): ~/.cursor/mcp.json. Per-project: <workspace>/.cursor/mcp.json.
{
"mcpServers": {
"packet-tracer": {
"command": "python",
"args": ["-m", "packet_tracer_mcp", "--stdio"]
}
}
}
Reload the Cursor window after saving (Cmd/Ctrl+Shift+P -> "Reload Window").
The vast majority of MCP clients accept the same three fields. Translate to whatever syntax your client expects:
For HTTP-only clients, start the server with python -m packet_tracer_mcp and point the client at http://127.0.0.1:39000/mcp.
2 — Ask your LLM to build a network
"Create a network with 2 routers, 2 switches, 4 PCs, DHCP and static routing"
The server handles the rest: planning -> validation -> generation -> deploy.
For live deploy into a running Packet Tracer instance, also paste the bootstrap snippet once into PT's Builder Code Editor. The MCP tools work even without it (you can still plan, generate scripts and configs, and export to disk).
◈ How It Works
Data Flow
TopologyRequest
|
Orchestrator --- IPPlanner (assigns /24 LANs + /30 inter-router links)
|
Validator --- 34 typed error codes, port/cable/IP checks
|
AutoFixer --- fixes wrong cables, upgrades routers, reassigns ports
|
TopologyPlan (validated, fully addressed)
|
+------------------+----------------------+----------------------+
▼ ▼ ▼ ▼
addDevice() addModule() addLink() configureIosDevice()
(place device) (HWIC/NIM/NM) (cable) configurePcIp()
| | | |
PTBuilder Script -- sent via HTTP bridge -▶ Packet Tracer Script Engine
Why Port 39000?
The server defaults to streamable-http (stdio is available via --stdio). When you run it in HTTP mode:
- Persistent - stays running, not restarted per editor session
- Multiple clients - VS Code, Claude Desktop, and others can connect simultaneously
- Shared state - the HTTP bridge to Packet Tracer stays alive across requests
- Debuggable -
curl http://127.0.0.1:39000/mcpor tail logs in the terminal - Decoupled - server lifecycle is independent from the editor
Port 39000 was chosen to avoid collisions with common ports (3000, 5000, 8000, 8080) and the internal bridge at 54321.
◈ MCP Tools
71 tools across 20 groups. Groups 1-12 cover the plan → deploy pipeline; groups 13-20 live-configure, inspect, and simulate any topology already on the canvas (they talk to the HTTP bridge directly, so they work on a freshly built topology or one you opened by hand).
Catalog
Estimation
Planning
pt_plan_topologyreturns machine-readable JSON. Use its output as input for all downstream tools.
Validation & Fixing
Generation
Full Pipeline
pt_full_buildreturns a human-readable report. It includes the JSON plan at the end for reference but is not intended as direct JSON input for other tools. Usept_plan_topologyfor that.
Live Deploy
Topology Interaction
Simulation & Packet Inspection
Export & Projects
Modules
Hot-install expansion modules (HWIC, NM, NIM, WIC) on routers already placed in the active topology. The runtime patch powers the device off, installs the module and powers it back on automatically - no manual shutdown needed.
Slot is a string that mirrors the addressing PT expects:
- HWIC on 1941/2901/2911 ->
"0/0","0/1","0/2","0/3"(chassis-slot/hwic-subslot)- NIM on ISR4321/4331 ->
"0","1"- NM on Router-PT / 2811 / 2620XM / 2621XM ->
"1","2"(ISR G2 like 2911/2901/1941 do not have NM slots - use 2x HWIC-2T for 4 serials)- Cloud-PT / hosts ->
"0","1", ... per the device's slot mapIntegers are accepted and auto-coerced to strings, but prefer the literal string format above to match PT's slot semantics - particularly for HWIC where
"0/0"and0address different slots.
ACL
Apply and remove Access Control Lists on live routers via the HTTP bridge. Works independently of pt_live_deploy - you can add ACLs to any existing topology.
When to use each type: Standard ACL (1-99) - filter by source IP only. Extended ACL (100-199) - filter by source, destination, protocol and ports. Named ACL - any string identifier, easier to read and edit in IOS.
NAT / PAT
Configure address translation on live routers via the HTTP bridge. Three modes map directly to the three IOS NAT variants taught in CCNA.
When to use each mode:
static- one private IP always maps to the same public IP. Use for servers that must be reachable from the internet with a fixed address.dynamic- pool of public IPs assigned on demand. Use when you have more public IPs than PAT justifies but fewer than private hosts.pat- many private IPs share one public IP using port numbers. Use in virtually every home and enterprise network (use_interface_overload=Trueuses the WAN interface IP directly).
Live Routing
Enable a routing protocol on a router that's already in the topology. Each tool confirms the config landed in PT (configureIosDevice returns OK) and returns the exact IOS lines it sent.
Live Switching & VLANs
Live L3 Services
Live Interfaces & WAN
Live Security & Universal Config
End Devices
Observe & Diagnostics
Read live state back from devices - turns the topology into a closed feedback loop (build → configure → verify).
◈ MCP Resources
5 read-only catalog resources accessible by any MCP client.
◈ Live Deploy Setup
The live deploy feature sends commands directly to a running Packet Tracer instance. No copy-pasting needed.
+----------+ MCP +------------------+ HTTP +-----------------+ $se() +--------------+
| LLM | -----▶ | MCP Server | ------▶ | PTBuilder | ------▶ | Packet Tracer|
| Copilot | | :39000 | :54321 | (WebView) | IPC | (Engine) |
+----------+ +------------------+ +-----------------+ +--------------+
Setup
Recommended — bundled auto-start extension. This repo ships V3-MCP-BUILDER.pts (the MCP-BUILDER extension): a Packet Tracer extension that hosts the bridge and starts polling :54321 automatically when PT loads it — no per-session snippet to paste.
- Copy
V3-MCP-BUILDER.ptsinto Packet Tracer's install-directoryextensions/folder, then restart Packet Tracer:- Windows:
C:\Program Files\Cisco Packet Tracer <version>\extensions\ - macOS / Linux: the
extensions/folder inside your Packet Tracer install
Use the install directory, not the per-user one. On PT 9.0 the per-user extensions folder (under your home/profile, e.g.
…\Cisco Packet Tracer 9.0.0\extensions\) is not scanned — the.ptsmust live in the install directory. On the first launch after copying it, PT shows a one-time "load this extension?" prompt → click Yes. (On Windows you may need to run Packet Tracer, or copy the file, as administrator to write intoProgram Files.) - Windows:
- After it loads, the MCP-BUILDER window opens automatically (or open it via Extensions -> MCP-BUILDER). Leave it visible — QtWebEngine freezes a hidden webview's timers, so the window must stay open (just park it in a corner) for the poll to keep running.
- Confirm with the
pt_bridge_statustool — it should report the bridge is active and PTBuilder is polling. Once connected, the live-deploy and live-config tools drive Packet Tracer directly.
Fallback — stock builder, once per session. If you'd rather use Packet Tracer's built-in builder, go to Extensions -> Builder Code Editor, paste this snippet and click 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)");
This injects a setInterval into the PTBuilder webview that polls the bridge every 500 ms. When the MCP server queues a command, PTBuilder picks it up and runs it in PT's Script Engine via $se('runCode', ...).
Technical note: PTBuilder's
executeCode()strips newlines internally (code.replace(/\n/g, "")), which is why the bootstrap uses/* */block comments instead of//line comments.
◈ Supported Devices
74 device models across 34 categories.
Routers (15)
Note: No router has Serial ports by default. Serial requires physical HWIC or NIM modules - see Expansion Modules.
Switches - Layer 2 (5)
Switches - Layer 2
Switches - Layer 3 (3)
End Devices (12)
Access Points & Wireless (8)
Security (2)
Wireless LAN Controllers (3)
Cloud / WAN (2)
Network Connectivity (4)
Modems (2)
Home / Consumer Routers (2)
IP Phone (1)
Meraki / SDN (2)
Network Controllers (2)
Telecom / Special (3)
Embedded / IoT (3)
Physical Infrastructure (5)
Device Aliases
101 aliases total - common names the LLM can use that resolve to actual models:
See infrastructure/catalog/aliases.py for the full 101-entry list.
◈ Cable Types
The server infers the correct cable automatically from the two device categories. You can also specify it explicitly.
Supported Cable Types (validated, usable in plans)
Cable Inference Rules
88 ordered category pairs are defined in
CABLE_RULES(infrastructure/catalog/cables.py); any pair not listed there falls back tostraight.coaxial,serial,fiber,consoleandphoneare never inferred - pass them explicitly on the link.
All PT Link Type Codes (reference)
◈ Expansion Modules
150 expansion modules across 26 module categories. They add extra ports to devices at runtime. The generator emits addModule() calls after addDevice() and before addLink(), which is the required PTBuilder execution order.
addDevice("R1", "2911", 100, 100);
addModule("R1", "0/0", "HWIC-2T"); // installs 2 serial ports in HWIC slot 0/0
addLink("R1", "Serial0/0/0", "R2", "Serial0/0/0", "serial");
HWIC / WIC Modules - for 1941, 2901, 2911
HWIC / WIC Modules
NIM Modules - for ISR4321, ISR4331
NM Modules - legacy routers (14 total)
Other Module Families
The catalog contains 150 modules total across all device types:
See infrastructure/catalog/modules.py for the complete list.
Automatic serial module selection
When serial routing is required, the server picks the right module automatically:
◈ IP Addressing
The IP planner assigns addresses automatically. No manual configuration needed.
Rules:
- Gateway is always
.1on each LAN subnet - PCs, Laptops and Servers get sequential IPs starting from
.2 - DHCP pools are created per LAN; the excluded range is
.1-.10(gateway plus room for static hosts), not just the gateway - DNS defaults to
8.8.8.8
Example - 2 routers, 2 LANs:
LAN 1: 192.168.0.0/24 -> R1 Gig0/0: 192.168.0.1 | PC1: 192.168.0.2 | PC2: 192.168.0.3
LAN 2: 192.168.1.0/24 -> R2 Gig0/0: 192.168.1.1 | PC3: 192.168.1.2 | PC4: 192.168.1.3
Link: 10.0.0.0/30 -> R1 Gig0/1: 10.0.0.1 | R2 Gig0/1: 10.0.0.2
◈ Routing Protocols
All 4 IGPs are fully implemented and generate real IOS commands.
Floating static routes (backup routes with AD=254) are supported - set floating_routes: true in the request.
Static routing uses BFS to compute multi-hop destination reachability, so even in topologies with 4+ routers all routes are generated correctly.
◈ Topology Templates
Templates are hints that guide the orchestrator's topology-building logic.
◈ Architecture
src/packet_tracer_mcp/
+-- adapters/
| +-- mcp/
| +-- tool_registry.py # All 71 MCP tools (@mcp.tool decorators)
| +-- resource_registry.py # All 5 MCP resources (@mcp.resource decorators)
|
+-- application/
| +-- dto/ # Request/Response data transfer objects
| +-- use_cases/ # One use case per tool (plan, validate, fix, ...)
|
+-- domain/
| +-- models/
| | +-- requests.py # TopologyRequest -- input from LLM
| | +-- plans.py # TopologyPlan, DevicePlan, LinkPlan, ModulePlan
| | +-- acls.py # ACLPlan, ACLEntry, ACLBinding
| | +-- nat.py # NATConfig, NATPool, NATStaticMapping (3 modes)
| | +-- errors.py # PlanError, ErrorCode (34 codes), ValidationResult
| +-- services/
| | +-- orchestrator.py # Main pipeline: request -> TopologyPlan
| | +-- ip_planner.py # Assigns /24 LANs and /30 inter-router links
| | +-- validator.py # Validates models, ports, cables, IPs
| | +-- auto_fixer.py # Fixes cables, upgrades routers, reassigns ports
| | +-- explainer.py # Natural-language plan explanation
| | +-- estimator.py # Dry-run device/link/config count estimation
| +-- rules/
| +-- device_rules.py # Validates device models against catalog
| +-- cable_rules.py # Validates cable types and port conflicts
| +-- ip_rules.py # Validates IP uniqueness and subnet conflicts
| +-- acl_rules.py # Validates ACL entries, numbers, wildcards
| +-- nat_rules.py # Validates NAT IPs, pool ranges, interface coherence
|
+-- infrastructure/
| +-- catalog/
| | +-- devices.py # 74 DeviceModel definitions across 34 categories
| | +-- modules.py # 150 expansion module specs (NM, HWIC, NIM, WIC, SFP...)
| | +-- cables.py # 15 cable types, PT codes, 88 inference rules
| | +-- aliases.py # 101 model name aliases
| | +-- templates.py # 9 topology template definitions
| +-- generator/
| | +-- ptbuilder_generator.py # Generates addDevice/addModule/addLink JS
| | +-- cli_config_generator.py # Generates IOS CLI blocks (DHCP, routing, ...)
| | +-- acl_cli_generator.py # Generates access-list / ip access-group CLI
| | +-- nat_cli_generator.py # Generates ip nat inside/outside / pool / overload CLI
| +-- execution/
| | +-- live_bridge.py # PTCommandBridge HTTP server (:54321)
| | +-- live_executor.py # Converts TopologyPlan -> JS commands -> bridge
| | +-- deploy_executor.py # Clipboard deploy + manual instructions
| | +-- manual_executor.py # File export executor
| +-- persistence/
| +-- project_repository.py # Save/load TopologyPlan as JSON projects
|
+-- shared/
| +-- enums.py # RoutingProtocol, DeviceCategory, CableType, ...
| +-- constants.py # Defaults, layout values, capabilities
| +-- utils.py # prefix_to_mask and other helpers
|
+-- server.py # FastMCP instance, registers tools/resources
+-- settings.py # Server config (version, host, port)
+-- __main__.py # python -m packet_tracer_mcp entry point
◈ Testing
# Run all tests
python -m pytest tests/ -v
# Single file
python -m pytest tests/test_full_build.py -v
# Specific test
python -m pytest tests/test_full_build.py::TestFullBuild::test_basic_2_routers -v
369 tests in 24 test_*.py files, covering: IP planning, plan validation, auto-fixer, plan explanation, estimator, PTBuilder script generation, CLI config generation, ACL/NAT/HSRP/IPv6/EtherChannel/port-security/SVI/static-route generators, MCP tool registration, and full-build integration. Expected output of python -m pytest tests/ -q:
369 passed in 2.54s
Main files:
◈ Requirements
Declared in pyproject.toml: requires-python = ">=3.11", mcp[cli]>=1.0.0, pydantic>=2.0.0. There is no lockfile - those are the only floors. Versions the 369-test suite was last verified against (2026-08-01): Python 3.14.6, mcp 1.27.2, pydantic 2.13.4, pytest 9.0.3, twofish 0.3.0, uvicorn 0.49.0.
pip install -e . also installs a console script pt-mcp, equivalent to python -m packet_tracer_mcp (add --stdio for stdio transport).
◈ Configuration
There are no environment variables and no config file. Everything is either a tool argument or a hardcoded constant.
Where output lands.
pt_exportwrites under<CWD>/projects/.pt_save_projectnever writes there - it asks Packet Tracer to save the.pktin place (fileSave), or to the absolutepathargument (fileSaveAsNoPrompt). When an MCP client spawns the server via stdio, the CWD is whatever directory the client launched from - not necessarily the repo.projects/,data/test_*and.venv/are in.gitignore, so a fresh clone contains none of them; they are recreated on first run. Nothing else has to be supplied by hand - there is no.env, no*.exampletemplate, and no secret of any kind in this repo.
◈ Troubleshooting
◈ Quick Example
Prompt: "Build a network with 2 routers, 2 switches, 4 PCs, DHCP and static routing"
pt_full_build output summary:
Devices (8): R1, R2 (2911), SW1, SW2 (2960-24TT), PC1, PC2, PC3, PC4 (PC-PT)
Links (7): R1<->R2 (cross), R1<->SW1 (straight), R2<->SW2 (straight),
SW1<->PC1, SW1<->PC2, SW2<->PC3, SW2<->PC4 (all straight)
IP Plan:
LAN 1: 192.168.0.0/24 -- R1 Gig0/0: .1, PC1: .2, PC2: .3
LAN 2: 192.168.1.0/24 -- R2 Gig0/0: .1, PC3: .2, PC4: .3
Link: 10.0.0.0/30 -- R1 Gig0/1: 10.0.0.1, R2 Gig0/1: 10.0.0.2
DHCP: Pools on R1 (192.168.0.0/24) and R2 (192.168.1.0/24)
Routes: Bidirectional static routes on R1 and R2
Generated: 8x addDevice, 7x addLink, 2x configureIosDevice, 4x configurePcIp
pt_live_deploy sends all 21 commands through the bridge and the topology appears in Packet Tracer fully configured.
◈ Offline Tools
Beyond the live MCP server, offline-tools/ contains standalone
utilities that read, write and author Packet Tracer's encrypted file formats
without running PT - useful for batch edits, CI, or adding canvas annotations
the live scripting API can't create:
.ptsextension modules - decrypt / re-encrypt (CAST-256-EAX, bit-perfect) and author new ones from scratch (pts_builder.py)..pkt/.pkasave files - decrypt / re-encrypt (Twofish-EAX, bit-perfect) and inject canvas notes + colored VLAN circles offline (pkt_inject_note.py, needs Twofish:pip install -e ".[offline]"orpip install twofish).
See offline-tools/README.md for details.
License
This project is licensed under the MIT License - free to use, fork, and modify.
MIT License (2026) - Mateo
Feel free to clone, modify, and use locally without restrictions.
Contributions welcome!
Built with MCP - Powered by Pydantic - Deploys to Cisco Packet Tracer
If this project is useful to you, star it and share it with the community ⭐