tshark-mcp

tshark-mcp

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 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 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):

   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.

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

Claude Code:

   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/mcpb@2.1.2 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:

   {

"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="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.
• 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

Fifty-eight tools. Every one returns JSON with a typed outputSchema, pages with limit 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/ , and --schema-profile full publishes them all. Only the default toolset (34 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 k