cisco-pt-mcp
Provides tools for automating Cisco Packet Tracer, including creating network topologies, adding and connecting devices, configuring IOS devices and PCs, and running monitoring and simulation workflows.
Integrates Google Gemini AI to generate network designs and PTBuilder code from natural-language descriptions, which can then be applied to Packet Tracer.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cisco-pt-mcp Create a small office network with one router, one switch, and three PCs."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.

β¨ 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.py2. Install Packet Tracer Extension
Open Cisco Packet Tracer
Extensions β Scripting β Configure PT Script Modules
Click Add β Select
extension/cisco-pt-mcp.ptsRestart Packet Tracer
3. Start & Connect
# Start the MCP server
python -m mcp_serverIn 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 |
| Generate complete network from text | "Create a small office network..." |
| Generate PTBuilder JavaScript | "Code for 5 switches in a ring" |
| Run PTBuilder code | Execute custom/generated code |
| Build from JSON specification | Import complex designs |
| Open the web UI | Access code editor & templates |
Core Network Tools
Tool | Description |
| Add router, switch, PC, or server |
| Install interface module (WIC, NIM, etc.) |
| Connect devices with cables |
| Delete devices |
| Remove connections |
| Rename devices |
| Reposition on canvas |
| Power device on/off |
Configuration Tools
Tool | Description |
| Set IP, subnet, gateway, DNS on PCs |
| Run IOS CLI commands on routers/switches |
Monitoring & Simulation Tools
Tool | Description |
| Snapshot of all devices and connections |
| Detailed device information |
| Switch simulation/realtime mode |
| Query simulation state |
| Step through packet flow |
| Send ICMP ping PDU |
| Read PDU outcomes |
| View IOS command history |
π Documentation
QUICKSTART.md - Get running in 5 minutes
SETUP_GUIDE.md - Complete setup & usage guide
packet-tracer-automation-build-doc.md - Advanced automation techniques
π 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 secondsExample 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.pyOption 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:
PTBuilder - JavaScript automation for PT
Gemini API - AI network generation
π 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 toolsaddDeviceA
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).
addLinkA
Connect two devices with a cable. Both interfaces must be free (in_use=false in getNetwork output). If unsure, call getNetwork first.
Inputs: linkType (required), device1Name (required), device2Name (required), device1Interface (required), +1 more.
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).
removeLinkB
Remove one or more cables. Each entry identifies one endpoint of the link.
Inputs: links (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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Talk to your public-facing AI from any MCP client β Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude with Cisco Packet Tracer 9.x to control network topologies, configure devices with IOS commands, and run diagnostics via natural language.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Cisco Packet Tracer in real time, allowing natural language-driven creation and configuration of network topologies.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI models to generate, validate, and deploy network topologies directly into Cisco Packet Tracer from natural-language prompts.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to drive Cisco Packet Tracer 8.x in the background, building topologies, auto-selecting cables so links come up green, running device CLI commands, reading back configuration, and exporting .pkt files without dialogs or stealing window focus.MIT