tshark-mcp

A read-only MCP server that lets an AI assistant analyse packet captures with tshark. Point it at a directory of pcap files, connect Claude or any other MCP client, and ask questions about the calls, sessions and subscribers in them.

Why

• Telecom captures need correlation, not grep. A failed attach, a dropped bearer or one-way audio spans Diameter, GTP, SIP, RTP and MAP. The tools pair requests with answers, name the result codes (Diameter 5420, GTP cause 78, Q.850 cause 16) and say what never got a reply.
• An agent with a shell and tshark is a liability. This server can only run tshark -r <file> on files inside directories you allow, under hard caps on size, packets, output and time. It cannot capture, write, export, resolve names or load code.
• It tells you when the capture itself cannot be trusted: duplicate packets from a SPAN session, bytes the capture missed, cut-short frames, checksum offload, clocks that run backwards.

Install and connect

1. Install tshark (it comes with Wireshark): brew install --cask wireshark, apt-get install tshark or dnf install wireshark-cli.

2. Install the server (Python 3.10 or newer):

   uv tool install git+https://github.com/Kx96xx/tshark-mcp
   # or: pipx install git+https://github.com/Kx96xx/tshark-mcp
   

   Requirements: Python 3.10+, tshark 4.0 or newer (tested with 4.2 and 4.6); the mcp (2.1+) and pydantic (2.12+) packages are installed automatically. The package is published as tshark-mcp-server (the PyPI name tshark-mcp belongs to an unrelated project); the command stays tshark-mcp. From a clone: uv tool install . or pipx install ..

3. Connect a client, naming the directory that holds your captures.

   Claude Code:

   claude mcp add tshark-mcp -- tshark-mcp --allow-dir /path/to/pcaps
   

   Claude Desktop (claude_desktop_config.json), Cursor, or any client that starts stdio servers:

   {
     "mcpServers": {
       "tshark-mcp": {
         "command": "tshark-mcp",
         "args": ["--allow-dir", "/path/to/pcaps"]
       }
     }
   }
   

   To run it by hand: tshark-mcp --allow-dir /path/to/pcaps [--allow-dir /more] [--log-file ~/tshark-mcp.jsonl]. TSHARK_MCP_ALLOW_DIRS (colon-separated) works instead of the flag. Three small synthetic captures to start with are in examples/.

What you can ask it

• "Which capture in this directory mentions IMSI 001010123456789, and when?"
• "Why did this subscriber's attach fail?" (Diameter result codes and the AVPs behind them)
• "Was the GTP session created? What cause came back, and which PAA?"
• "What is our ASR to this destination, and did post-dial delay go up?"
• "Why is there one-way audio on this call?"
• "What was the call quality: loss, jitter, MOS?"
• "Why can't this UE register on IMS?" and "Where did the SMS go?"
• "Is this a purge storm? How often is the MME looping?"
• "Where does the failing capture first differ from the working one?"
• "Which DNS resolver is failing, and for which names?"
• "Is the upload slow because of the network, the server or the receiver?"
• "Can I trust the loss numbers in this file at all?"
• "What does Experimental-Result 5420 mean, and which spec section do I quote?"

One real answer, trimmed. The capture is examples/sip_one_way_audio.pcap: a SIP call where the called side never sends media. The agent finds the Call-ID with sip_dialogs, then calls:

media_path_check(path="/captures/sip_one_way_audio.pcap", call_id="one-way-audio-1@ue.example")

{
  "offer":  {"message": "INVITE", "media_endpoint": "198.51.100.9:40010", "codecs": ["PCMA/8000", "telephone-event/8000"]},
  "answer": {"message": "200 INVITE", "media_endpoint": "192.0.2.70:30010", "codecs": ["PCMA/8000", "telephone-event/8000"]},
  "directions": [
    {"direction": "offerer to answerer", "expected": "198.51.100.9:40010 > 192.0.2.70:30010",
     "streams": [{"ssrc": "0x6a6a6a6a", "packets": 250, "codec": "PCMA/8000", "first_frame": 6}], "status": "as negotiated"},
    {"direction": "answerer to offerer", "expected": "192.0.2.70:30010 > 198.51.100.9:40010", "streams": [], "status": "missing"}
  ],
  "issues": [{"kind": "one_way_media", "detail": "no RTP seen answerer to offerer (192.0.2.70:30010 > 198.51.100.9:40010): one-way audio as captured"}],
  "verdict": "no RTP seen answerer to offerer (192.0.2.70:30010 > 198.51.100.9:40010): one-way audio as captured"
}

The caller's RTP arrived exactly where the SDP answer asked for it and nothing came back, so the fault is behind the media gateway, not the caller's NAT or codec. Every row carries frame numbers (first_frame: 6), so packet_detail can show the packet behind any claim. More worked examples, one per tool, are in docs/TOOLS.md; a full investigation of a failed attach is in docs/EXAMPLE.md.

Safety model

• Read-only by construction. The only program started is tshark, from an argv list with -n and -r, never a shell. Capture, write, export and extension flags are refused before a process exists. tshark gets an empty profile, so no personal Lua script, plugin or extcap loads, and at most two tshark processes run at once.
• Allowlist and caps. Every path must resolve inside an --allow-dir. File size (500 MB), packets dissected per call (500), frames read per run (200 000), JSON per call (30 KB) and run time (60 s) are capped; the numbers are configurable, none can be switched off.
• Packet text is data, not instructions. Strings copied from packets are cleaned, capped and named in untrusted_text_fields. Optional redaction (--redact ids) replaces IMSIs, MSISDNs, IMEIs, SIP users and UE addresses with stable tokens before anything leaves the server.

Transport is stdio only; --transport streamable-http is for local experiments and has no authentication. Details, the full caps table and the redaction rules: docs/SAFETY.md. How to report a vulnerability: SECURITY.md.

Tools

Forty-one tools. Every one returns JSON with a typed outputSchema, pages with limit and offset, and returns failures as {"error": {...}} with isError: true and a fix hint. The tool list is compact by default (102 KB instead of 263 KB at 41 tools); each tool's full schema is the resource schema://tools/<name>, and --schema-profile full publishes them all. Full arguments, fields and examples: docs/TOOLS.md.

Redaction

Telecom captures carry IMSIs, MSISDNs, IMEIs, SIP users and UE addresses. Start the server with --redact ids (or TSHARK_MCP_REDACT=ids), or pass redact="ids" on a call, and those values come back as stable keyed tokens such as imsi:3f2a9c1b0d that still join across tools and work as arguments in later calls. ids+ips hides every IP address too. A call can raise the server's level, never lower it. What is found, what is not, and how the pre-scan works: docs/SAFETY.md.

Limitations

• No live capture, by design. The server reads files that already exist and nothing else.
• No decryption: IPsec, TLS and ciphered NAS are reported as tshark sees them. tls_handshakes reads only the clear part of the handshake; after a TLS 1.3 ServerHello its outcome is inferred from the record pattern and says so.
• Large captures are slow. tshark reads the whole file for every call; a 500 MB capture with a selective filter takes tens of seconds, so prefer pre-sliced captures.
• Pairing follows what is in the file. A request whose answer was captured on another interface is unanswered; one the capture stopped too soon to answer is also near_capture_end. How GTP responses are matched across NATs and proxies is in docs/TOOLS.md.
• MAP decoding relies on tshark's dissectors; a segmented XUDT whose other segments are missing is reported as segmented, not guessed.

Roadmap

1. 5G core: HTTP/2 SBI (Nnrf, Nausf, Nsmf).
2. Streaming per-call progress so a long tshark run can be cancelled from the client.
3. Optional S1AP/NGAP and NAS summaries with EMM/ESM cause names.

Development

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

The suite is 835 tests and runs in about a minute; CI runs it on Python 3.10 to 3.13 with the tshark that Ubuntu 24.04 ships (4.2). Every capture the tests use is synthetic, built by tests/pcapgen.py at run time with documentation addresses and test identities, and the three captures under examples/ come from the same generator, so nothing in the repository contains traffic from a real network (the list of scenarios is in docs/TOOLS.md). Conventions for contributors and for agents: CONTRIBUTING.md, AGENTS.md.

Licence

MIT, Copyright (c) 2026 Karl Hulse.