io.github.bx33661/wireshark-mcp

---

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

---

Install

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

Wireshark MCP 3.0 uses 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

Restart your AI client — done.

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.

---

Tools

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

Category	Highlights	Count
Entry & Workflow	wireshark_open_file, wireshark_quick_analysis	2
Packet Analysis	Packet list, details, bytes, context, stream follow, search, file info	8
Data Extraction	HTTP requests, DNS queries, arbitrary fields, object export	4
Statistics	Aggregate/group/distinct/top-k/time buckets, protocol hierarchy, endpoints, conversations, I/O graph, expert info, service response time, flow graph	8
Security & Anomaly	Credential scan, port scan, DNS tunnel, DoS, beaconing, exfiltration, protocol anomalies, YARA	8
Protocol Analysis	wireshark_analyze_protocol (20 protocols), TCP health, ARP spoofing	3
Decrypt & Dissection	TLS/WPA decrypt, decryption check, decode-as, protocol preferences	5
Forensics & Enrichment	TLS fingerprints, file signature scan, GeoIP	3
File Ops, Capture & Suite	Live capture, interfaces, merge, filter-save, editcap trim/split/dedup/time-shift, frame extract, text2pcap, capabilities	11

One tool covers 20 protocols rather than 20 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 ~22 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:

Profile	Tools	Payload	Drops
full (default)	52	~22 KB	nothing
analysis	40	~17 KB	live capture, interface listing, all file-writing tools
core	32	~14 KB	the above, plus decryption, dissection overrides, and low-level views

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 11 that create files (live capture, merge, filter-save, editcap, text2pcap, frame extract, object export).

In 3.0, those 11 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

Topic	Link
Documentation index	docs/README.md
Capture-wide aggregation	docs/aggregation.md
Platform setup (macOS/Linux/Windows)	docs/platform-validation.md
Manual client configuration	docs/manual-configuration.md
Deployment scenarios	docs/deployment-scenarios.md
3.0 security migration	docs/security-hardening-v3.md
Prompt templates	docs/prompt-engineering.md
Architecture	docs/architecture.md
Release checklist	docs/release-checklist.md
Contributing	CONTRIBUTING.md
Changelog	CHANGELOG.md
Feature roadmap	ROADMAP.md
Security policy	SECURITY.md

---

Development

pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

See CONTRIBUTING.md for the full guide.

---