Packet Tracer MCP Server

Tell your AI "create a network with 3 routers, OSPF and DHCP" — the server plans the topology, validates everything, generates the scripts and configs, and deploys it directly into Cisco Packet Tracer in real time.

Python 3.11+ · Pydantic 2.0+ · FastMCP · Streamable HTTP · v0.4.0

Preview

MCP server running — tools and resources exposed in OpenAI Codex CLI

MCP server connected in Claude Code — ready to receive tool calls

MCP server connected in Claude Code using Arch Linux — ready to receive tool calls

Table of Contents

1. What It Does
2. Installation
3. Quick Start
4. How It Works
5. MCP Tools
6. MCP Resources
7. Live Deploy Setup
8. Supported Devices
9. Cable Types
10. Expansion Modules
11. IP Addressing
12. Routing Protocols
13. Topology Templates
14. Architecture
15. Testing
16. Requirements

What It Does

This is a Model Context Protocol (MCP) server that gives any LLM (GitHub Copilot, Claude, etc.) full programmatic control over Cisco Packet Tracer. It exposes 22 MCP tools and 5 MCP resources that 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)
        |  PTBuilder Script Engine
  Cisco Packet Tracer
  -- devices created
  -- cables connected
  -- IOS configs applied

Key features:

• Plan complex topologies from a single natural-language description
• Automatic IP addressing (LAN /24 + inter-router /30)
• Auto-DHCP pool generation per LAN
• Static, OSPF, EIGRP and RIP routing config generation
• Plan validation with 15 typed error codes + auto-fixer
• Real-time deploy to a live Packet Tracer instance via HTTP bridge
• Export plans, scripts and configs to files
• 74 device models across 34 categories, 150 expansion modules, 15 cable types

Installation

git clone https://github.com/Mats2208/MCP-Packet-Tracer
cd MCP-Packet-Tracer
pip install -e .

Quick Start

1. Start the server

python -m packet_tracer_mcp

This starts two servers:

• MCP server at http://127.0.0.1:39000/mcp — receives tool calls from your editor
• HTTP bridge at http://127.0.0.1:54321 — sends commands to PTBuilder inside Packet Tracer

Both start automatically. No extra scripts needed.

For stdio mode (debug/legacy): python -m packet_tracer_mcp --stdio

2. Connect your MCP client

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"
    }
  }
}

3. 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.

How It Works

Data Flow

TopologyRequest
      |
  Orchestrator ---- IPPlanner (assigns /24 LANs + /30 inter-router links)
      |
  Validator   ---- 15 typed error codes, port/cable/IP checks
      |
  AutoFixer   ---- fixes wrong cables, upgrades routers, reassigns ports
      |
  TopologyPlan (validated, fully addressed)
      |
  +--------------------+----------------------+----------------------+
  v                    v                      v                      v
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 uses streamable-http instead of stdio. This means:

• 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/mcp or 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

22 tools across 7 groups.

Catalog

Estimation

Planning

pt_plan_topology returns machine-readable JSON. Use its output as input for all downstream tools.

Validation & Fixing

Generation

Full Pipeline

pt_full_build returns 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. Use pt_plan_topology for that.

Live Deploy

Topology Interaction

Export & Projects

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 (once per PT session)

1. Open Cisco Packet Tracer 8.2+
2. Go to Extensions → Builder Code Editor
3. Paste this bootstrap script 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 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 (7)

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

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, "HWIC-2T");       // installs 2 serial ports in slot 0
addLink("R1", "Serial0/0/0", "R2", "Serial0/0/0", "serial");

HWIC / WIC Modules — for 1941, 2901, 2911

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 .1 on each LAN subnet
• PCs, Laptops and Servers get sequential IPs starting from .2
• DHCP pools are created per LAN with the gateway excluded from the pool
• 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 22 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
│   │   └── errors.py              # PlanError, ErrorCode (15 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
│
├── 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, ...)
│   ├── 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

38 tests covering: IP planning, plan validation, auto-fixer, plan explanation, estimator, PTBuilder script generation, CLI config generation, and full-build integration.

Requirements

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.