Skip to main content
Glama

PT Tutor

A troubleshooting tutor for Cisco Packet Tracer, built on the Model Context Protocol.

It reads the student's live network, finds the fault, and teaches them to find it too.

published tests npm Packet Tracer 9 Node 20+ MCP License: MIT


Most AI tools for Packet Tracer build and fix the lab for you. PT Tutor does the opposite: it works out what's wrong, then asks the next good question, the way a lab instructor would. The student makes every change.

Features

  • Read-only by design. Only status commands (show, ping, traceroute, ipconfig) can run. Configuration commands are refused.

  • Real diagnosis. It walks the path in both directions (cabling, interfaces, VLANs, trunks, gateways, routes, ACLs, DHCP) and checks its verdict with a live ping.

  • Hint ladder. Every finding has three levels: a nudge, a pointer to where to look, then the concept. No level hands over the configuration.

  • Assessment guard. If a graded activity (.pka) is open, it switches to hint-only mode. It says where the problem is, not what it is. If it can't tell whether the file is graded, it assumes it is.

Related MCP server: ptlab

How it works

Claude  ──MCP──▶  PT Tutor server  ──file mailbox──▶  Packet Tracer script module
                  (Node.js)          ~/.pt-tutor        (reads the live network)

A small script module inside Packet Tracer exchanges files with the server in ~/.pt-tutor/mailbox. It opens no network port, and it accepts only a short list of read-only commands.

Getting started

Requirements: Packet Tracer 9.0, Node.js 20 or newer, and an MCP client such as Claude Code or Claude Desktop.

1. Get the Packet Tracer module

npx -y pt-tutor-mcp bridge

This saves pt-tutor-bridge.pts in the current folder.

2. Add it to Packet Tracer

  1. Open Extensions → Scripting → Configure PT Script Modules.

  2. Click Add and choose pt-tutor-bridge.pts.

  3. Give the module file access in its permission settings, then start it.

3. Connect your MCP client

claude mcp add pt-tutor -- npx -y pt-tutor-mcp

For Claude Desktop, add it to claude_desktop_config.json:

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

4. Try it. Open a lab, break something, and ask for help. In Claude Code, run:

/mcp__pt-tutor__tutor PC1 can't reach the server

Tools

Tool

Purpose

pt_status

Connection check, the open file, and the current tutor mode

get_topology

Devices, ports and links on the canvas

get_device_state

Interfaces, addresses, routes and VLANs of one device

run_command

One read-only command on a device

diagnose

Why a source can't reach a destination (10–60 s)

tutor_hint

The next hint for a finding

For instructors

Set PT_TUTOR_MODE in the server's env:

Value

Behaviour

auto (default)

Hint-only during graded activities, full hints otherwise

hint-only

Hint-only for every lab

An unrecognised value also means hint-only, so a typo can't turn the guard off. The setting lives in the MCP config, so on shared machines keep that file somewhere students can't edit.

Limitations

  • Packet Tracer 9 only. Developed on macOS; Windows and Linux are untested.

  • Static routing, VLANs, trunks and ACLs are checked in depth. OSPF and EIGRP are read from the routing table only.

  • The commands the tutor runs appear in the device's console history.

Development

git clone https://github.com/faithere1/pt-tutor-mcp.git && cd pt-tutor-mcp
npm install
npm test                       # build and run the test suite (no Packet Tracer needed)
node tools/build-release.mjs   # write the release bridge with dev commands off

See PROGRESS.md for the architecture, the dev setup and the Packet Tracer API notes.

Getting help

Found a bug or a wrong diagnosis? Open an issue. Contributions are welcome; see CONTRIBUTING.md.

License

MIT

Available Tools

6 tools
diagnoseDiagnose connectivityA
Read-only

Explain why one device can or cannot reach another. Reads the whole live network (addressing, gateways, VLANs, trunks, interface state, routing tables, static routes, ACLs, proxy ARP), walks the path hop by hop in both directions, and runs a real ping to confirm. Returns findings with a code, the device and interface, evidence and the concept involved. In tutor mode, use the findings to ask guiding questions; do not paste the fix. Pass a finding to tutor_hint to get a graded hint. In hint-only mode the findings are redacted to where the problem is (device, interface, area) and a ref for tutor_hint. Takes 10-60 seconds on larger labs.

Inputs: source (required), destination (required), ping.

get_device_stateGet device stateA
Read-only

Detailed state of one device: every port (IP, mask, MAC, admin and line status, neighbour), plus the key show output for its kind. Routers get 'show ip interface brief' and 'show ip route'. Switches add 'show vlan brief' and 'show interfaces trunk'. End devices get 'ipconfig /all'. Read-only.

Inputs: device (required).

get_topologyGet network topologyA
Read-only

List every network device on the Packet Tracer canvas (name, type, model, power) with its cabled or addressed ports, and every link with its up/down state. Read-only.

Inputs: includeNonNetwork.

pt_statusPacket Tracer statusA
Read-only

Check that Packet Tracer is connected and report its version, the open file, and whether that file is a graded activity (.pka). Call this first. tutorMode is "hint-only" during a graded activity or when an instructor has set it for every lab (hintOnlyReason says which): diagnose hides what is wrong, hints stop at level 2, and the configuration can't be read. Guide them with questions; never give the configuration that solves the activity.

Inputs: no named parameters.

run_commandRun a read-only commandA
Read-only

Run one read-only command on a device's terminal and return its output. IOS devices (routers, switches) accept 'show ...', 'ping' and 'traceroute'. End devices (PCs, servers) accept 'ipconfig', 'ping', 'tracert', 'arp -a', 'nslookup' and 'netstat'. Configuration commands are refused: the student makes the changes, the tutor only looks. In hint-only mode, 'show running-config' and 'show startup-config' are refused too.

Inputs: device (required), command (required).

tutor_hintGet a tutor hintA
Read-only

Get a hint for a finding from diagnose, at one of three levels. Pass either the finding's code, or its ref when diagnose returned redacted findings. Level 1 is a nudge towards the problem area without naming the device. Level 2 names the device and a read-only command to look at. Level 3 explains the concept. No level gives the fix. Start at level 1 and only go up after the student has tried and is still stuck. Put the hint in your own words, as a question where you can. In hint-only mode the highest level is 2.

Inputs: level (required), ref, code, device, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: status, topology, per-device state, command execution, diagnosis, and hints. The main overlap is between get_device_state and run_command, since both can return show output, but their descriptions clarify aggregate state versus a single read-only command.

    Naming Consistency3/5

    The names are all readable snake_case, but the conventions are mixed: get_topology/get_device_state/run_command use verb_noun, while pt_status, diagnose, and tutor_hint do not. This is not chaotic, but it is not a predictable verb_noun pattern throughout.

    Tool Count5/5

    Six tools is well-scoped for a read-only Packet Tracer tutoring workflow. Each tool has a distinct role in the inspection, diagnosis, and hinting flow.

    Completeness4/5

    The toolset covers connection status, topology, device state, command inspection, diagnosis, and leveled hints, which is a coherent read-only lifecycle. Minor gaps might include retrieving activity instructions or broader lab context, but the core tutoring and diagnostic surface is present.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables network troubleshooting through an MCP Streamable HTTP endpoint, exposing diagnostic tools for Cisco Packet Tracer labs with human-in-the-loop review and NIST/CIS security validation.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-capable AI clients to inspect live lab topology, manage terminal sessions, run commands, collect evidence, and support network investigation, troubleshooting, and validation while engineers retain control over managed definitions and decisions.
      7
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to build and troubleshoot Cisco Packet Tracer networks by adding devices, cabling them, pushing IOS configurations, addressing interfaces, configuring routing, running pings, and reading/writing .pkt files without Packet Tracer open.
      42
      62 PyPI
      MIT