Mcp Tracer

mcp-tracer

English | Español

An MCP server that lets any AI agent design Cisco Packet Tracer topologies. The agent builds the network through tools, mcp-tracer validates it and turns it into a script for the PTBuilder extension, and you run that script in Packet Tracer.

[npm version] [CI] [License: MIT]

Website: mcp-tracer-web.vercel.app, a step-by-step overview with setup for each AI client.

mcp-tracer is an independent project. It is not affiliated with, endorsed or sponsored by Cisco Systems, Inc., nor by PTBuilder or its author. See the disclaimer.

Contents

• How it works
• Requirements
• Installation
• Configuration
• Tools, resources and prompts
• Complete example
• Validation and limitations
• Development
• Disclaimer
• License

How it works

1. You describe a network to your AI agent in plain language.
2. The agent calls mcp-tracer tools (build_topology, or add_device, add_link, configure_device, configure_pc…). The server keeps the topology in memory and rejects invalid input on the spot: unknown models, ports a model doesn't have, a port used twice, IOS commands on a PC.
3. validate_config reports what is left: errors (the script would fail or abort in Packet Tracer) and warnings (it may not work as intended).
4. generate_script returns a JavaScript script for PTBuilder, or export_script writes it to a .js file.
5. You paste the script into Extensions > Builder Code Editor in a new, empty Packet Tracer workspace and click Run. PTBuilder creates the devices and cables, applies the IOS configuration and sets the host IP addresses.

flowchart LR    U([You]) -- "describe the network" --> A["AI agent (MCP client)"]    A -- "tool calls" --> S["mcp-tracer: in-memory topology"]    S -- "validate_config" --> V{"errors?"}    V -- "yes: fix and retry" --> A    V -- "no" --> G["PTBuilder script"]    G -- "you copy and paste it" --> P["Packet Tracer: Builder Code Editor, Run"]

mcp-tracer does not control Packet Tracer. It never connects to it: it can't see your workspace, link lights or show output, and it can't change a network that is already running. It only generates a script, which you run yourself. The topology lives in the server's memory and is lost when the MCP client restarts the server; use save_topology to keep it.

Requirements

• Node.js 20 or later (npx comes with it).
• Cisco Packet Tracer 8.x or 9.x, available from Cisco Networking Academy.
• The PTBuilder extension, installed separately in Packet Tracer:
  1. Download Builder.pts from the PTBuilder repository.
  2. In Packet Tracer open Extensions > Scripting > Configure PT Script Modules.
  3. Click Add… and select Builder.pts. (One user on PT 9.0.0 also had to click Run in that dialog.)
  4. Extensions > Builder Code Editor now opens the editor where you paste the scripts.
• An MCP client that runs local stdio servers, such as Claude Desktop, Claude Code or Cursor.

Installation

No global install is needed. MCP clients start the server with:

npx -y mcp-tracer

Run by hand, the server prints one line to stderr ([mcp-tracer] info: v0.1.1 running on stdio) and then waits for an MCP client on stdin/stdout. That is expected.

From source

git clone https://github.com/aldoogando03-bit/mcp-tracer.gitcd mcp-tracernpm cinpm run build

Then point your client at node with the absolute path to build/index.js (see below).

Configuration

Every client below uses the same server entry. Restart the client (or reload its MCP servers) after editing its configuration.

Claude Desktop

Open Settings > Developer > Edit Config, or edit the file directly:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{  "mcpServers": {    "mcp-tracer": {      "command": "npx",      "args": ["-y", "mcp-tracer"]    }  }}

Claude Code

claude mcp add mcp-tracer -- npx -y mcp-tracer

Add --scope project to share it with your team through a .mcp.json file in the project root, which you can also write by hand:

{  "mcpServers": {    "mcp-tracer": {      "command": "npx",      "args": ["-y", "mcp-tracer"]    }  }}

On native Windows (not WSL), wrap npx in cmd /c: claude mcp add mcp-tracer -- cmd /c npx -y mcp-tracer.

Cursor

Use the same mcpServers JSON in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json for every project.

Other MCP clients

MCP is an open standard, so mcp-tracer works with any MCP client that can launch local stdio servers; only the place where you register it changes. After that, you ask for the network in plain language and the AI calls the tools itself. There is no special command to type.

These clients read the same mcpServers JSON shown for Claude Desktop:

• VS Code (GitHub Copilot agent mode): Copilot's portable ~/.copilot/mcp-config.json takes this JSON. A workspace's .vscode/mcp.json and the user mcp.json (MCP: Open User Configuration) use VS Code's own format instead, shown below.
• Windsurf / Devin Desktop: in the Cascade panel, open the ... menu and click Open MCP config file in the MCPs section.
• Cline: click the MCP Servers icon, open the Configure tab and click Configure MCP Servers.
• LM Studio 0.3.17 or later: in the Program tab of the right sidebar, click Install > Edit mcp.json.
• Gemini CLI: ~/.gemini/settings.json for every project, or .gemini/settings.json in a project. Or run gemini mcp add -s user mcp-tracer npx -- -y mcp-tracer (without -s user it writes the project file).

VS Code's own format has a servers key and a type:

{  "servers": {    "mcp-tracer": {      "type": "stdio",      "command": "npx",      "args": ["-y", "mcp-tracer"]    }  }}

Zed uses a context_servers key in its settings.json (zed: open settings file):

{  "context_servers": {    "mcp-tracer": {      "command": "npx",      "args": ["-y", "mcp-tracer"]    }  }}

OpenAI Codex (CLI and IDE extension) reads ~/.codex/config.toml, or .codex/config.toml in a trusted project:

[mcp_servers.mcp-tracer]command = "npx"args = ["-y", "mcp-tracer"]

Or run codex mcp add mcp-tracer -- npx -y mcp-tracer.

To set MCP_TRACER_DIR, add an env object next to args (in Codex, a [mcp_servers.mcp-tracer.env] table). On Windows, if a client can't start the server, run npx through cmd /c as in the Windows note.

Model note. The client's model has to handle tool calling well. Small local models may struggle with large topologies. The built-in prompts (vlan_lab, ospf_lab, dhcp_lab, nat_lab) help, because they already contain the computed topology.

ChatGPT on the web and on mobile is not supported yet: it only connects to remote MCP servers over HTTPS, and mcp-tracer runs locally over stdio. The ChatGPT desktop app shares Codex's MCP configuration, so the Codex setup above applies to it, or you can add mcp-tracer as a STDIO server under Settings > MCP servers.

From a source checkout

{  "mcpServers": {    "mcp-tracer": {      "command": "node",      "args": ["/absolute/path/to/mcp-tracer/build/index.js"]    }  }}

MCP_TRACER_DIR

save_topology, load_topology and export_script resolve relative paths against MCP_TRACER_DIR if it is set, and otherwise against the server's working directory, which MCP clients often set to something arbitrary. A leading ~ means your home directory. Absolute paths always work.

The file tools only accept their own extensions, case-insensitively: .json for save_topology and load_topology, .js or .txt for export_script. Anything else, such as .cmd or .bat, is refused, so a tool call can never write an executable file. A path that names a directory (~, ., .., a bare drive such as C:, or an existing folder) or contains : in the file name is refused too. Paths are not confined to MCP_TRACER_DIR; restricting them to it is a possible future option.

{  "mcpServers": {    "mcp-tracer": {      "command": "npx",      "args": ["-y", "mcp-tracer"],      "env": { "MCP_TRACER_DIR": "C:\\Users\\you\\Documents\\pt-labs" }    }  }}

With Claude Code: claude mcp add --env MCP_TRACER_DIR=/home/you/pt-labs mcp-tracer -- npx -y mcp-tracer.

Windows note

If a client fails to start the server (for example spawn npx ENOENT), run npx through cmd:

{  "mcpServers": {    "mcp-tracer": {      "command": "cmd",      "args": ["/c", "npx", "-y", "mcp-tracer"]    }  }}

Agent skill (optional)

The repository also ships a skill, skills/mcp-tracer/SKILL.md, that tells an agent when and how to use these tools: build with build_topology, always run validate_config, then hand over the script and the steps to run it. It does not replace the server; install both:

npx skills add aldoogando03-bit/mcp-tracer

Tools, resources and prompts

Tools

Device names are case-insensitive and must be unique. A name has 1 to 64 characters: letters, digits, spaces and . _ ( ) / -, starting with a letter or digit (R1, Core SW (1)); constructor and prototype are reserved. Port names can be abbreviated (Gi0/0 becomes GigabitEthernet0/0, Fa0/1 becomes FastEthernet0/1). Coordinates (x, y) go from -100000 to 100000. Arguments marked ? are optional.

Inputs have size limits: 500 devices and 2000 links per topology, 64 characters for model and port names, 32 for addresses and masks, and up to 2000 IOS commands of 512 characters each per call and per device.

Cables (cable): straight, cross, roll, fiber, serial, console, phone, coaxial, auto, octal, usb, custom_io. Leave it out and the server picks one: straight between unlike devices (router or host to switch or hub), cross between like devices (switch to switch, router to router, router to PC, PC to PC), straight from an access point to a switch or hub and cross to a router or host, serial for Serial ports and console for Console/RS232 ports. auto, roll, octal, usb and custom_io are passed to PTBuilder as given, and their behaviour there is unverified.

Models. The catalog covers these PTBuilder keys:

• Routers: 1841, 1941, 2811, 2901, 2911, ISR4321, ISR4331
• Switches: 2950-24, 2950T-24, 2960-24TT
• Multilayer switches: 3560-24PS (preferred), 3650-24PS (see limitations)
• Hosts: PC-PT, Server-PT, Laptop-PT, Printer-PT
• Other: Hub-PT, Cloud-PT, AccessPoint-PT, Linksys-WRT300N, 5505, 5506-X, 7960

Any other key of PTBuilder's device table (such as Router-PT or Switch-PT) is accepted, but its ports and cables are not checked. The safest set today is 2911, 2960-24TT, PC-PT and Server-PT, whose most-used port names are verified against primary sources. The built-in prompts use only those, plus 3560-24PS.

Resources

Prompts

Each prompt returns step-by-step instructions for the agent: the exact build_topology arguments with the addressing already worked out, the follow-up tool calls and the checks to run in Packet Tracer. All arguments are optional; invalid values fall back to the defaults, with a note.

In Claude Code the prompts appear as slash commands, such as /mcp__mcp-tracer__vlan_lab.

Complete example

This is the small-office-dhcp example. The outputs below come from the server itself.

You:

Build a small office in Packet Tracer: one router, one switch and three PCs on 192.168.1.0/24. The router should hand out the addresses by DHCP.

The agent calls build_topology:

{  "devices": [    { "name": "R1", "model": "2911" },    { "name": "S1", "model": "2960-24TT" },    { "name": "PC1", "model": "PC-PT" },    { "name": "PC2", "model": "PC-PT" },    { "name": "PC3", "model": "PC-PT" }  ],  "links": [    { "dev1": "R1", "port1": "GigabitEthernet0/0", "dev2": "S1", "port2": "GigabitEthernet0/1" },    { "dev1": "PC1", "port1": "FastEthernet0", "dev2": "S1", "port2": "FastEthernet0/1" },    { "dev1": "PC2", "port1": "FastEthernet0", "dev2": "S1", "port2": "FastEthernet0/2" },    { "dev1": "PC3", "port1": "FastEthernet0", "dev2": "S1", "port2": "FastEthernet0/3" }  ],  "ios": [    {      "name": "R1",      "commands": [        "hostname R1",        "ip dhcp excluded-address 192.168.1.1 192.168.1.10",        "ip dhcp pool OFFICE",        "network 192.168.1.0 255.255.255.0",        "default-router 192.168.1.1",        "exit",        "interface GigabitEthernet0/0",        "ip address 192.168.1.1 255.255.255.0",        "no shutdown",        "exit"      ]    },    { "name": "S1", "commands": ["hostname S1"] }  ],  "pcs": [    { "name": "PC1", "dhcp": true },    { "name": "PC2", "dhcp": true },    { "name": "PC3", "dhcp": true }  ]}

Topology built: 5 devices, 4 links, 2 IOS configs, 3 host IP configs.

No cables and no coordinates were given, so the server infers the cables and lays the devices out in rows. Next, validate_config:

Warnings (1):- [UNVERIFIED_PORT] S1 (2960-24TT): port names FastEthernet0/2 and FastEthernet0/3 are unverified in Packet Tracer; if PT names a port differently, its addLink fails silently.
No errors: generate_script will run. Warnings point at things that may not work in Packet Tracer.

The warning is expected: the 2960-24TT's FastEthernet0/2-24 follow Cisco's naming, but only FastEthernet0/1 has been confirmed so far. Finally, generate_script returns the script:

/* Generated by mcp-tracer v0.1.1 - paste into Extensions > Builder Code Editor and click Run */addDevice("R1", "2911", 250, 100);addDevice("S1", "2960-24TT", 250, 250);addDevice("PC1", "PC-PT", 100, 400);addDevice("PC2", "PC-PT", 250, 400);addDevice("PC3", "PC-PT", 400, 400);addLink("R1", "GigabitEthernet0/0", "S1", "GigabitEthernet0/1", "straight");addLink("PC1", "FastEthernet0", "S1", "FastEthernet0/1", "straight");addLink("PC2", "FastEthernet0", "S1", "FastEthernet0/2", "straight");addLink("PC3", "FastEthernet0", "S1", "FastEthernet0/3", "straight");configureIosDevice("R1", "hostname R1\nip dhcp excluded-address 192.168.1.1 192.168.1.10\nip dhcp pool OFFICE\nnetwork 192.168.1.0 255.255.255.0\ndefault-router 192.168.1.1\nexit\ninterface GigabitEthernet0/0\nip address 192.168.1.1 255.255.255.0\nno shutdown\nexit");configureIosDevice("S1", "hostname S1");configurePcIp("PC1", true);configurePcIp("PC2", true);configurePcIp("PC3", true);

It also returns the same warning as a second text block.

Run it in Packet Tracer

1. File > New, so the workspace is empty. Running a script in a workspace that already has these devices duplicates them.
2. Extensions > Builder Code Editor.
3. Paste the whole script, replacing anything already in the editor, and click Run.
4. Wait until every link light is green. Switch ports take about 30 seconds.

Check that it works

• PC1 > Desktop > IP Configuration shows DHCP with an address from 192.168.1.11 up and gateway 192.168.1.1. If it shows 169.254.x.x, click DHCP again once the links are green.
• PC1 > Desktop > Command Prompt: ipconfig, then ping 192.168.1.1 and a ping to PC2's address.
• R1 > CLI: show ip interface brief (GigabitEthernet0/0 up/up) and show ip dhcp binding (one lease per PC).

Validation and limitations

Errors and warnings

Most mistakes are rejected when the tool is called. validate_config is the final check before the script is generated, and it also catches problems in files opened with load_topology. Codes are stable, so agents and scripts can rely on them.

Errors mean the script would fail or abort in Packet Tracer. They block generate_script and export_script unless force: true is passed.

Warnings mean the script runs, but part of it may not work as intended: EMPTY_TOPOLOGY, UNCATALOGUED_MODEL, POWER_3650, SERIAL_NEEDS_MODULE, CABLE_UNVERIFIED, CABLE_SUSPICIOUS, UNVERIFIED_PORT, ISOLATED_DEVICE, PCIP_UNVERIFIED_PORT, HOST_STATIC_NO_GATEWAY, GATEWAY_NOT_IN_SUBNET, DUPLICATE_IP. Each message explains the issue and how to fix it.

Limitations

• Nothing has been verified in a real Packet Tracer run yet. The PTBuilder API was researched from its source code and Cisco's documentation (docs/PTBUILDER_API.md). Many port names, such as most 2960 ports, the ISR4321/4331 ports, the 3560/3650 ports and console ports, follow Cisco's naming but are unconfirmed. They are flagged by UNVERIFIED_PORT and marked verified: false in pt://catalog. Reports of verified names are very welcome.
• No modules. PTBuilder's addModule isn't supported yet, so routers have no serial ports (use Ethernet between routers), and SFP uplinks and IP phone power adapters can't be added.
• 3650-24PS power. In Packet Tracer the 3650-24PS ships without a power supply, and PTBuilder could not add one, so it may stay off. Use 3560-24PS.
• Silent failures in PT. The script doesn't check what addDevice and addLink return, so a device or link that PT refuses is simply missing. Invalid IOS commands also fail silently. A configureIosDevice or configurePcIp call for a device that doesn't exist throws and stops the rest of the script.
• Run each script once, in an empty workspace. Running it again, or in a workspace that already has devices, duplicates them.
• PTBuilder is a separate install, and it only does what its API offers. Server services, such as the Server-PT DHCP service in dhcp_lab, must be set up by hand, and host addressing is IPv4 only.
• No live control. mcp-tracer doesn't read back the state of Packet Tracer (see How it works).

Development

npm cinpm run build

To try the server by hand, use the MCP Inspector: npx @modelcontextprotocol/inspector node build/index.js.

CLAUDE.md describes the architecture, the conventions and the rules for the script generator. CONTRIBUTING.md explains how to contribute; see also the changelog.

Disclaimer

mcp-tracer is an independent, community project. It is not affiliated with, endorsed or sponsored by Cisco Systems, Inc. Cisco and Cisco Packet Tracer are trademarks or registered trademarks of Cisco Systems, Inc. and/or its affiliates. They are used here only to describe what this software works with.

mcp-tracer is also not affiliated with PTBuilder or its author. PTBuilder is a separate project with its own terms; its repository declares no license. mcp-tracer does not include or redistribute any PTBuilder code. It generates scripts that call PTBuilder's functions, and you install PTBuilder yourself from its repository. Its documentation (docs/PTBUILDER_API.md) describes how PTBuilder behaves in its own words and links to PTBuilder's source instead of copying it. mcp-tracer uses the model-key names that PTBuilder's API accepts (such as ISR4331 or PC-PT) only for interoperability.

You need your own, properly obtained copy of Cisco Packet Tracer.

License

MIT © 2026 Aldo Ariel Ogando Peña (A-TECH)