PacketMaster

MCP server for network-troubleshooting PCAP analysis via tshark. Pairs with Cursor skills pcap-troubleshooting (domain workflows) and packetmaster-mcp (MCP tool usage).

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• Wireshark with CLI tools: tshark, capinfos

brew install wireshark   # macOS

PacketMaster auto-detects `/Applications/Wireshark.app/Contents/MacOS/tshark` if not on PATH.

Install

cd "/Users/networkze/Documents/Claude Projects/PacketMaster"
uv sync --extra dev

Cursor MCP Configuration

Install the launcher (once), then add to ~/.cursor/mcp.json:

mkdir -p ~/.packetmaster-mcp
cp scripts/start-mcp.sh ~/.packetmaster-mcp/start-mcp.sh
chmod +x ~/.packetmaster-mcp/start-mcp.sh

{
  "mcpServers": {
    "packetmaster": {
      "command": "/Users/networkze/.packetmaster-mcp/start-mcp.sh",
      "env": {
        "FASTMCP_SHOW_SERVER_BANNER": "false"
      }
    }
  }
}

Uses a launcher script (like flipper-zero) because Cursor can break uv run paths that contain spaces.

PCAP paths must be absolute. By default any readable .pcap on disk is allowed. Set PM_ALLOWED_DIRS only if you want an opt-in sandbox.

Environment Variables

Variable	Default	Description
PM_ALLOWED_DIRS	(unset)	Optional colon-separated allowlist; when set, paths must stay inside
PM_REQUIRE_ALLOWED_DIRS	false	If true, PM_ALLOWED_DIRS must be set or startup validation fails
PM_MAX_FILE_SIZE	10GB	Max PCAP file size
PM_MAX_PACKETS	10000	Max packets per extraction request
PM_MAX_STDOUT_BYTES	10MB	Max subprocess stdout
PM_TIMEOUT	300	Subprocess timeout (seconds)
PM_HASH_MAX_BYTES	500MB	Skip SHA-256 above this size unless requested
PM_REDACT_SENSITIVE	true	Redact credentials in stream/field output
TSHARK_PATH	auto	Override tshark binary path

Tools

Tool	Description
pm_check_install	Verify tshark/capinfos installation
pm_file_info	capinfos + optional SHA-256
pm_protocol_hierarchy	Protocol distribution
pm_conversations	Top conversations by bytes
pm_endpoints	Top IP endpoints
pm_expert_info	Wireshark expert information
pm_tcp_anomalies	TCP retrans/dup ACK/zero window/OOO/RST
pm_latency_summary	Per-flow RTT statistics
pm_io_stats	Traffic over time
pm_extract_fields	Paginated field extraction
pm_follow_stream	Follow TCP/UDP/HTTP/TLS stream (redacted)
pm_filter_packets	Packet summaries by display filter
pm_detect_capture_type	Start here — wlan vs ethernet + tool routing
pm_wired_quick_scan	EPC/SPAN — DHCP, DNS, ICMP, VLAN, L2 infra, TCP
pm_dhcp_analysis	DHCP phases, stuck patterns, optional MAC filter
pm_dns_analysis	DNS queries/responses, NXDOMAIN, top names
pm_asymmetric_hints	One-sided capture / path asymmetry heuristics
pm_troubleshoot_quick_scan	L3 TCP-focused composite (alternate to wired scan)
pm_troubleshoot_flow	Deep dive between two IPs
pm_wifi_quick_scan	802.11 monitor — retries, mgmt, roaming, BSSIDs
pm_wifi_client_analysis	Deep dive on one STA by MAC
pm_wifi_roaming_analysis	802.11k/v roam timeline for one STA

Workflow with NetOps EPC

1. Capture via ios_xe_epc_capture_run (user-netops MCP) with pull_pcap=true
2. Run pm_troubleshoot_quick_scan on the returned local_path
3. Drill down with pm_troubleshoot_flow on suspect IPs

Development

uv run pytest -q
uv run packetmaster-mcp   # stdio MCP server

Security

• PCAP paths must be absolute; optional PM_ALLOWED_DIRS sandbox for locked-down setups
• Symlinks rejected
• Stream/field output redacts Authorization, Bearer tokens, passwords by default
• Confirm with user before pm_follow_stream on production captures