tshark-mcp

tshark-mcp

[CI] [PyPI] [Downloads] [Python 3.10 to 3.13] [Licence MIT]

Ask your AI assistant why a call, an attach or a session failed, and get the answer from your own pcap, with frame numbers. tshark-mcp is a read-only MCP server: it runs tshark -r on captures in directories you allow, pairs requests with answers across Diameter, GTP, SIP/RTP, SIGTRAN, DNS, TCP and TLS, and names the cause codes.

claude mcp add tshark-mcp -- uvx --from tshark-mcp-server tshark-mcp --allow-dir /path/to/pcaps

(needs uv and tshark; other clients below)

[A real MCP client session: sip_dialogs and media_path_check on the one-way audio example]

_{A live session, not a mock-up: an MCP client starts the PyPI package over stdio and calls two tools on examples/sip_one_way_audio.pcap. Recorded with vhs from docs/media/demo.tape.}

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, resolve names or load code, and it writes nothing unless the operator turns on export_subset with --export-dir.
• 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. Run the server from PyPI with uv (nothing to install; Python 3.10 or newer):

   sh

   uvx --from tshark-mcp-server tshark-mcp --allow-dir /path/to/pcaps

   Or install it once and use the tshark-mcp command: uv tool install tshark-mcp-server or pipx install tshark-mcp-server.

   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 ..

   Or build the container (tshark included, non-root, captures mounted read-only): docker build -t tshark-mcp ., then use docker run --rm -i --read-only --tmpfs /tmp --cap-drop ALL --network none -v /path/to/pcaps:/captures:ro tshark-mcp as the server command.

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

   Claude Code:

   sh

   claude mcp add tshark-mcp -- uvx --from tshark-mcp-server tshark-mcp --allow-dir /path/to/pcaps

   Or as a Claude Code plugin (the server plus seven investigation skills; needs uv), which asks for the capture directory and redaction when enabled:

   /plugin install tshark-mcp --marketplace Kx96xx/tshark-mcp

   Claude Desktop as an extension: python mcpb/build.py && npx -y @anthropic-ai/[email protected] pack build/mcpb build/tshark-mcp.mcpb, then open build/tshark-mcp.mcpb and pick the capture directories.

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

   json

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

   With uv tool install or pipx, use "command": "tshark-mcp" and drop the first three args.

   MCP Registry clients (VS Code and the directories that index the registry) find it as io.github.Kx96xx/tshark-mcp: they run the PyPI package with uvx and ask for TSHARK_MCP_ALLOW_DIRS, the one required setting. Each GitHub release publishes the new version there (server.json).

   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/.

Found a bug or a wrong answer?

• A wrong or misleading answer: open a Wrong answer issue with the tool call, the output excerpt, what you expected and the plain tshark command that shows it.
• A crash or error: open a Bug issue with the tool call, the error, and your tshark, Python and OS versions.
• A security problem: report it privately through GitHub private vulnerability reporting (SECURITY.md), not in an issue.
• Questions: Discussions.

Never attach a capture with real subscriber data (IMSI, MSISDN, IMEI, IP addresses) to a public issue. Share the tool call and its output, and if a capture is needed, a minimal synthetic or anonymised one (--redact ids+ips masks identifiers in the output, not in the file).

What you can ask it

Start with "What is wrong in this capture?": the assistant calls incident_summary, which runs every check the capture's protocols allow and returns ranked findings with frame numbers and the next call to make, plus the protocols it has no check for. Then ask the specific question:

• "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="[email protected]")

{  "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.
• One write tool, off by default. export_subset writes a filtered subset of a capture to a NEW pcapng file, only when the server was started with --export-dir DIR (a directory outside every --allow-dir), never overwrites, never writes elsewhere and is capped by --export-max-mb (50). Without the flag it refuses every call.
• 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

and offset, takes start/end to read one time window of a capture (ISO 8601, epoch seconds, "+120s" after the capture start, "-30s" before its end), and returns failures as {"error": {...}} with isError: true and a fix hint. The tool list is compact by default (less than half the size of the full list); each tool's full schema is the resource schema://tools/<name>, and --schema-profile full publishes them all. Only the default toolset (33 tools, about 60% of the list: incident_summary, the capture overview, the most used TCP/IP and telecom tools) is listed unless you add --toolsets mobile,voice,network (or all); see AGENTS.md. Full arguments, fields and examples: docs/TOOLS.md. Every tool with limit also takes output="summary" (the summary plus three rows, under 8 KB), columns (row keys to keep) and max_output_kb (a lower cap for one call); every result says what it cost in tokens_estimate.

Prompts

Six MCP prompts turn the common investigations into guided workflows: the tool calls in order, what to cite, when to stop and the shape of the answer. Claude Code shows them as /mcp__tshark-mcp__<name>. The path arguments complete to capture files under the allowed directories (at most 50 names per answer, never outside the allowlist).

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/activatepip install -e '.[dev]'pytestpython -m evals            # task-success scenarios over the stdio server (docs/EVALS.md)

The suite 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). Sixteen task-success scenarios (docs/EVALS.md) check that the right tool answers an operator's question with the right facts; a model-driven mode is there and off by default. Conventions for contributors and for agents: CONTRIBUTING.md, AGENTS.md.

Licence

MIT, Copyright (c) 2026 Karl Hulse.