Wireshark MCP

Wireshark MCP

Give your AI assistant a packet analyzer.

*Drop a .pcap file, ask questions in plain English — get answers backed by real tshark data.*

English • 中文 • Docs • Changelog • Roadmap • Contributing

---

What is this?

An MCP server that wraps tshark (and optional Wireshark suite tools) into a structured analysis interface. Works with Claude Desktop, Claude Code, Cursor, VS Code, and 18+ other MCP clients.

You:    "Find all DNS queries going to suspicious domains in this capture."

Claude: [calls wireshark_extract_dns_queries → wireshark_detect_dns_tunnel] "Found repeated high-entropy DNS queries consistent with tunneling: ..."

New in 4.0

• Capture index. With the optional [index] extra, wireshark_index dissects a capture once into a local DuckDB file. Later wireshark_aggregate and wireshark_extract_fields calls read it with answers identical to tshark: 408× faster at 1 GB, and at 10 GB it answers questions the tshark path stops on. It also adds read-only SQL, capture sets, first-seen timelines, capture or window diffs and Parquet export. See Capture index.
• One finding shape. Every detector returns data.findings with a stable id, evidence anchors, a native tshark command to re-check it and candidate ATT&CK techniques.
• Case files. wireshark_case keeps captures, recorded results, findings and analyst verdicts in a JSON case file, so a long investigation survives a context reset. See Findings and cases.

Upgrading from 3.x needs no configuration change. Scripts that parsed the plain-text output of wireshark_detect_beaconing, wireshark_detect_exfiltration, wireshark_detect_protocol_anomalies, wireshark_detect_arp_spoofing, wireshark_yara_scan or wireshark_quick_analysis should read the JSON envelope instead. Full notes: 4.0.0 changelog.

---

Install

Claude Code / Codex plugin route

Prerequisites: uv and Wireshark CLI (tshark). The plugin includes this project and both skills; the client runs the locked Python project through uv over stdio. It does not install Wireshark or capture drivers.

From a checkout containing these plugin manifests, choose your client:

# Codex

codex plugin marketplace add . codex plugin add wireshark-mcp@wireshark-mcp

Claude Code

claude plugin marketplace add . claude plugin install wireshark-mcp@wireshark-mcp

See plugin distribution for local installation, old-version refresh, environment settings and the GitHub entrypoint after publication. Choose this route or the traditional registration route below, not both.

Traditional Python package route

Prerequisites: Python 3.10+ and Wireshark with tshark on PATH.

Wireshark MCP runs on the stable MCP Python SDK 2.x line (mcp>=2.1.1,<3).

pip install wireshark-mcp

wireshark-mcp install # choose from detected MCP clients

For scripts/non-interactive terminals, select clients explicitly. Preview before installing into the current project:

wireshark-mcp install --client codex --scope project --dry-run

wireshark-mcp install --client codex --scope project

The default scope is global. Repeat --client or explicitly use --client all. Restart the client to load configuration. See the installation guide for updates, removal, backups and exit codes.

Optional extras add features on top of the base install: index (DuckDB capture index for large captures), geoip (GeoIP enrichment) and yara (YARA scanning), or all:

pip install 'wireshark-mcp[index]'

The container image and the plugin route ship without extras. Every setting, extra and limit is listed in the configuration reference.

The project also ships MCP and full TShark CLI analysis skills; see skill discovery and usage.

Run wireshark-mcp doctor if anything looks off. See docs/manual-configuration.md for manual setup or platform-specific notes.

---

Quick Start

Point your AI client at a .pcap file and try:

Analyze capture.pcap using the Wireshark MCP tools.

Start with wireshark_open_file, then run wireshark_quick_analysis. Use wireshark_aggregate for any capture-wide count or distribution. Write findings to report.md.

For a large capture, or several related ones, build the index first and keep the investigation in a case file:

Index big.pcapng with wireshark_index, then use wireshark_aggregate and

wireshark_index action="timeline" to find when 10.0.0.5 first appeared. Open a case with wireshark_case, record every detector result you rely on, and verify each conclusion with wireshark_get_packet_details.

---

Tools

54 tools, each backed by real tshark output — organized into categories:

One tool covers 25 protocols rather than 25 tools covering one each: wireshark_analyze_protocol takes a protocol argument (tls_handshakes, mqtt, modbus, s7comm, zigbee, wifi, rtp, kerberos, …) and applies the right fields and display filter for it. The field names are the point — s7comm.param.item.dbnum is not something a caller should have to guess, and a wrong guess returns an empty result that reads like a clean capture.

The server starts with only tshark required. Optional tools (capinfos, mergecap, editcap, dumpcap, text2pcap) are auto-detected and enable extra features when present.

Context cost

The tool list travels in the prompt prefix of every request your client sends, so its size is a fixed per-request cost. The default surface is ~23 KB — about 9 KB of parameter schema, 5 KB of descriptions, and 3 KB of read/write annotations — and it is byte-identical across restarts so clients can cache the prefix rather than re-reading it each session.

If your client never captures live traffic or writes pcaps, --profile advertises less:

wireshark-mcp serve --profile core

Runtime prompts and protocol recommendations respect the selected profile. Static guides may describe full-only workflows, but the server never recommends an excluded tool during capture discovery.

Tool results are bounded too, since a result stays in the conversation for the rest of the session. Output over 8000 characters is truncated head-and-tail with a marker, and the tool's offset / limit / display_filter parameters are the way to page through the rest. Raise or lower the ceiling with:

export WIRESHARK_MCP_MAX_RESULT_CHARS=16000

Every tool also declares whether it reads or writes, so clients can auto-approve the 41 read-only analysis tools and still prompt for the 12 that create files (live capture, merge, filter-save, editcap, text2pcap, frame extract, object export, case files). wireshark_index is marked non-destructive: it writes only the server's own index cache.

Since 3.0, those tools fail closed until WIRESHARK_MCP_ALLOWED_DIRS names existing directories. Remote HTTP/SSE binding also stays loopback-only unless --allow-insecure-http is explicitly supplied behind a trusted authenticated TLS proxy. See the 3.0 security migration guide.

---

Documentation

| Ch