Skip to main content
Glama

cisco-pt-mcp πŸš€

AI-powered Cisco Packet Tracer automation - Let AI clients control Packet Tracer with natural language. Open source MCP server with Gemini AI integration.

Demo

✨ Features

  • πŸ€– AI Network Generation - Describe networks in plain English, get working topologies

  • 🎨 Visual Builder Interface - Web-based code editor with syntax highlighting

  • πŸ“¦ Ready-Made Templates - Campus, branch office, VLAN, routing configurations

  • πŸ”Œ MCP Protocol - Works with Claude Desktop, Cursor, and other MCP clients

  • ⚑ Real-time Control - Direct bridge to running Packet Tracer instance

  • πŸ› οΈ Complete Toolset - 20+ tools for device management, configuration, and testing


Related MCP server: packet-tracer-mcp

πŸ“₯ Quick Install

1. Install MCP Server

# Clone or download this repository
cd cisco-pt-mcp

# Install with AI support
pip install -e ".[ai]"

# Configure Gemini API (optional, for AI features)
python setup_config.py

2. Install Packet Tracer Extension

  1. Open Cisco Packet Tracer

  2. Extensions β†’ Scripting β†’ Configure PT Script Modules

  3. Click Add β†’ Select extension/cisco-pt-mcp.pts

  4. Restart Packet Tracer

3. Start & Connect

# Start the MCP server
python -m mcp_server

In Packet Tracer:

  • Click Extensions β†’ Packet Tracer MCP

  • Status should show "MCP Connected"

πŸ“– See QUICKSTART.md for detailed instructions


🎯 Usage Modes

Mode 1: AI Generator (Natural Language)

Open the PTBuilder interface in Packet Tracer and use the AI Generator tab:

"Create a corporate network with 1 edge router, 1 core switch, 
2 department switches, and 3 PCs per department. Configure VLANs."

Click Generate β†’ Network appears in workspace!

Mode 2: Code Editor (JavaScript)

Write PTBuilder code directly:

addDevice("R1", "2911", 150, 150);
addDevice("S1", "2960-24TT", 350, 150);
addLink("R1", "GigabitEthernet0/0", "S1", "GigabitEthernet0/1", "straight");
configureIosDevice("R1", "interface Gi0/0\nip address 192.168.1.1 255.255.255.0");

Mode 3: MCP Client (Claude/Cursor)

Configure your MCP client:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cisco-pt-mcp": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/cisco-pt-mcp",
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

Then chat with Claude:

"Create a network lab for testing OSPF routing with 3 routers"


πŸ› οΈ Available Tools

AI-Powered Tools

Tool

Description

Example

generateNetworkFromDescription

Generate complete network from text

"Create a small office network..."

generateCodeSnippet

Generate PTBuilder JavaScript

"Code for 5 switches in a ring"

executeBuilderCode

Run PTBuilder code

Execute custom/generated code

buildNetworkFromDesign

Build from JSON specification

Import complex designs

openBuilderInterface

Open the web UI

Access code editor & templates

Core Network Tools

Tool

Description

addDevice

Add router, switch, PC, or server

addModule

Install interface module (WIC, NIM, etc.)

addLink

Connect devices with cables

removeDevice

Delete devices

removeLink

Remove connections

renameDevice

Rename devices

moveDevice

Reposition on canvas

setPower

Power device on/off

Configuration Tools

Tool

Description

configurePcIp

Set IP, subnet, gateway, DNS on PCs

configureIosDevice

Run IOS CLI commands on routers/switches

Monitoring & Simulation Tools

Tool

Description

getNetwork

Snapshot of all devices and connections

getDeviceInfo

Detailed device information

setSimulationMode

Switch simulation/realtime mode

getSimulationStatus

Query simulation state

stepSimulation

Step through packet flow

sendPdu

Send ICMP ping PDU

getPduResults

Read PDU outcomes

getCommandLog

View IOS command history


πŸ“š Documentation


πŸŽ“ Examples

Example 1: Simple Network with AI

Prompt: "Create a basic network with one 2911 router, one 2960 switch, 
and two PCs. Configure the router with IP 192.168.1.1 and the PCs 
with static IPs in the same subnet."

Result: Complete working network in 30 seconds

Example 2: Campus Network Template

Load the "Campus Network" template from the Templates tab:

  • 3-tier architecture (core, distribution, access)

  • 1 core switch

  • 2 distribution switches

  • 4 access switches

  • Proper inter-switch connections

Example 3: VLAN Configuration

// From templates - VLAN setup
addDevice("S1", "2960-24TT", 300, 200);
addDevice("PC1", "PC-PT", 150, 300);
addDevice("PC2", "PC-PT", 450, 300);

configureIosDevice("S1", `
vlan 10
name Sales
vlan 20
name Engineering

interface FastEthernet0/1
switchport mode access
switchport access vlan 10

interface FastEthernet0/2
switchport mode access
switchport access vlan 20
`);

πŸ”§ Configuration

Gemini API Setup

Option 1: Interactive

python setup_config.py

Option 2: Environment Variable

export GEMINI_API_KEY="your_key_here"

Option 3: Config File Create ~/.cisco-pt-mcp/config.json:

{
  "gemini_api_key": "YOUR_KEY_HERE",
  "bridge_host": "127.0.0.1",
  "bridge_port": 7531,
  "tool_timeout": 60
}

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   MCP Client    β”‚  (Claude Desktop, Cursor, etc.)
β”‚  (Natural Lang) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚ MCP Protocol
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   MCP Server    β”‚  (Python)
β”‚   + Gemini AI   β”‚  - Network generation
β”‚                 β”‚  - Code generation
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚ Socket.IO (port 7531)
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ PT Extension    β”‚  (JavaScript)
β”‚  cisco-pt-mcp   β”‚  - PTBuilder integration
β”‚                 β”‚  - Web interface
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚ IPC API
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Packet Tracer   β”‚  (Cisco Application)
β”‚   Workspace     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

🀝 Contributing

Contributions welcome! This project integrates:


πŸ“„ License

MIT License - See LICENSE file


πŸ™ Acknowledgments

  • PTBuilder by kimmknight - JavaScript automation framework

  • MCP Protocol - Standard for AI-application communication

  • Google Gemini - AI generation capabilities

  • Original cisco-pt-mcp by muhammadbalawal


πŸ†˜ Support & Issues

  • Troubleshooting: See SETUP_GUIDE.md

  • Issues: Open an issue on GitHub

  • Documentation: Check the docs folder

Star ⭐ this repo if you find it useful!

Available Tools

23 tools
addDeviceA

Add a network device to the workspace. Call getNetwork first if unsure whether the chosen deviceName is already taken; names must be unique.

Inputs: x (required), y (required), deviceName (required), deviceModel (required).

addModuleA

Add an interface module to a device. Powers the device off, installs the module, powers it back on.

Inputs: slot (required), model (required), deviceName (required).

buildNetworkFromDesignA

Build a complete network in Packet Tracer from a structured design specification. Accepts a JSON design with devices, links, and configurations. Useful for importing designs or building from AI-generated specifications.

Inputs: design (required), clear_existing.

configureIosDeviceA

Execute IOS commands on a router or switch. Commands run from global config and are saved with 'write memory'.

Inputs: commands (required), deviceName (required).

configurePcIpB

Configure IP settings on a PC or end device.

Inputs: deviceName (required), dnsServer, ipaddress, subnetMask, +2 more.

executeBuilderCodeB

Execute PTBuilder JavaScript code in Packet Tracer. The code can use PTBuilder functions like addDevice, addLink, configurePcIp, configureIosDevice, etc. This is useful for batch operations and programmatic network building.

Inputs: code (required).

generateCodeSnippetA

Use AI (Gemini) to generate PTBuilder JavaScript code from a natural language description. Returns executable JavaScript code that can be run in the PTBuilder code editor. Requires GEMINI_API_KEY environment variable or ~/.cisco-pt-mcp/config.json with gemini_api_key.

Inputs: description (required).

generateNetworkFromDescriptionA

Use AI (Gemini) to generate a complete network topology from a natural language description. Returns a full network design including devices, links, IP addressing, and configurations. Requires GEMINI_API_KEY environment variable or ~/.cisco-pt-mcp/config.json with gemini_api_key.

Inputs: description (required), auto_build.

getCommandLogA

Read the IOS command history logged by Packet Tracer. Optionally filter by device name and cap the number of returned entries.

Inputs: limit, deviceName.

getDeviceInfoB

Detailed info about one device, including interfaces and incident links.

Inputs: deviceName (required).

getNetworkA

Snapshot of the entire workspace: every device, its interfaces (with in_use flags), and every cable. Call this before addLink or removeDevice when unsure of current state.

Inputs: no named parameters.

getPduResultsA

Read the outcome of PDUs in the current simulation β€” source, destination, traffic type, and status (accepted/dropped/in_transit/etc). Call after stepSimulation to verify connectivity. Use the types filter to show only ICMP, TCP, etc. and hide STP/DTP background noise.

Inputs: types.

getSimulationStatusA

Query the current simulation state: mode (realtime or simulation), elapsed simulation time, PDU frame count, and current frame index.

Inputs: no named parameters.

moveDeviceA

Move a device to new coordinates on the logical workspace canvas.

Inputs: x (required), y (required), deviceName (required).

openBuilderInterfaceA

Open the PTBuilder code editor interface in Packet Tracer. This provides a web-based code editor where users can write and execute JavaScript code to automate network building.

Inputs: no named parameters.

removeDeviceB

Remove one or more devices from the workspace.

Inputs: deviceNames (required).

renameDeviceA

Rename an existing device. The new name must be unique in the workspace.

Inputs: newName (required), deviceName (required).

sendPduA

Add an ICMP ping PDU between two devices using PT's native Simple PDU mechanism. Automatically enables simulation mode if not already active. Use stepSimulation to advance and getPduResults to check if the ping succeeded.

Inputs: sourceDevice (required), destinationDevice (required).

setPowerC

Power a device on or off.

Inputs: power (required), deviceName (required).

setSimulationModeA

Switch Packet Tracer between simulation mode and realtime mode. Simulation mode is required before sending PDUs or stepping through traffic.

Inputs: toSimMode (required).

stepSimulationA

Step the simulation forward or backward, or reset it entirely. PT must already be in simulation mode (use setSimulationMode first).

Inputs: direction (required), steps.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools have clearly distinct targets: device lifecycle, link management, configuration, simulation, and automation. The main source of ambiguity is the set of network-generation tools (generateNetworkFromDescription, buildNetworkFromDesign, generateCodeSnippet, executeBuilderCode), but their descriptions do clarify whether they design, build, or execute code.

    Naming Consistency5/5

    All tool names follow a consistent camelCase verb-noun style, such as addDevice, removeLink, configureIosDevice, getNetwork, and setSimulationMode. Even longer names like generateNetworkFromDescription and buildNetworkFromDesign extend the same predictable pattern.

    Tool Count4/5

    23 tools feels somewhat heavy, but the set covers several distinct functional areas: device management, cabling, configuration, simulation, PDU traffic, command logging, and PTBuilder automation. While a few tools could be consolidated, each area is represented and none feels completely redundant.

    Completeness4/5

    The toolset covers the core lifecycle for devices and links, configuration, power control, simulation stepping, PDU sending/result checking, and scripted builder automation. Minor gaps exist, such as no direct tool for removing configurations or setting specific interface VLANs, but most network-building and troubleshooting workflows are reachable.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers