mcp-wireshark
# mcp-wireshark
> Community-maintained MCP server for [Wireshark](https://www.wireshark.org/) / `tshark`. Not affiliated with Wireshark or Anthropic.
> Give your AI assistant direct access to packet captures. Ask Claude to summarize a `.pcap`, follow a TCP stream, filter for a specific protocol, or capture live traffic — all without leaving the chat.

[](https://badge.fury.io/py/mcp-wireshark)
[](https://github.com/khuynh22/mcp-wireshark/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
---
## Quick start with Claude Code
```bash
pip install mcp-wireshark
claude mcp add --transport stdio --scope user mcp-wireshark -- mcp-wireshark
```
That's it. Open Claude Code and try:
> "Summarize ./capture.pcap and tell me which IPs talked the most."
`--scope user` makes the server available across every Claude Code project. Drop the flag to install it for the current project only. See [`claude mcp` docs](https://code.claude.com/docs/en/mcp) for more.
### Verify the install
```bash
claude mcp list
```
You should see `mcp-wireshark` listed. Inside Claude Code, ask:
> "Run check_installation."
If `tshark` is on your `PATH`, it returns the version. If not, see [troubleshooting](#troubleshooting).
---
## Tools
The server exposes 14 tools, split cleanly between **read tools** (safe, no side effects) and **write tools** (capture traffic or write files). Both groups are annotated with the standard MCP `readOnlyHint` so any compliant client can surface the distinction.
### Read tools
Safe to call freely — they only inspect state.
| Tool | What it does |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `check_installation` | Verify tshark is installed and show version |
| `list_interfaces` | List network interfaces available to capture from |
| `read_pcap` | Read packets from a `.pcap` / `.pcapng` file (preview + total count) |
| `display_filter` | Apply a Wireshark display filter to a pcap |
| `summarize_pcap` | High-level summary: I/O stats, protocol hierarchy, top talkers |
| `stats_by_proto` | Protocol hierarchy statistics |
| `follow_tcp` | Reassemble a TCP stream and return its payload |
| `follow_udp` | Reassemble a UDP stream and return its payload |
| `expert_info` | tshark expert analysis: warnings, errors, and notes grouped by severity |
| `decode_protocol` | Extract protocol fields as a TSV table. Curated defaults for HTTP, DNS, TLS, GOOSE, MMS, SV, SIP, ICMP; arbitrary fields for any other protocol |
| `protocol_stats` | Aggregate `-z` reports (protocol hierarchy, conversations, endpoints, HTTP/DNS/SMB stats) |
| `analyze_iec61850` | Health triage for GOOSE/SV/MMS captures: per-source OK/WARN/FAIL with sqNum/stNum gaps, TTL violations, smpCnt discontinuities, lost sync, and MMS errors |
### Write tools
These create files or capture live traffic. Compliant clients may prompt before invoking.
| Tool | What it does |
| -------------- | -------------------------------------------------------------------------- |
| `live_capture` | Capture live traffic from an interface (capped at 5 minutes / 10k packets) |
| `export_json` | Export packets from a pcap to a JSON file at a path you choose |
---
## See it in action
These clips run the real tools against [`demo/demo.pcapng`](demo/demo.pcapng) — a
short home-network capture. Regenerate them with `python demo/render_gif.py <scene>`.
**`summarize_pcap` — characterize an unknown capture at a glance**

**`decode_protocol` — filter to a protocol and get a compact table (here: TLS SNI and DNS-over-HTTPS lookups)**

**`expert_info` — let tshark surface the warnings and anomalies for you**

---
## Example prompts
Drop these into Claude Code as-is:
```
List my network interfaces.
Summarize ./traffic.pcap.
From ./traffic.pcap, show me only HTTP requests.
Follow TCP stream 0 in ./traffic.pcap and tell me what protocol is in it.
Capture 30 seconds of traffic on Wi-Fi filtered to tcp.port == 443.
Export every DNS packet from ./traffic.pcap to ./dns.json.
Decode the GOOSE messages in ./substation.pcapng — only stNum >= 1.
Run expert analysis on ./traffic.pcap and group findings by severity.
Show me the IP conversations in ./traffic.pcap.
```
### Useful display filters
| Filter | Matches |
| ------------------------------------------ | ------------------------------- |
| `tcp.port == 80` | HTTP |
| `tcp.port == 443` | HTTPS |
| `dns` | All DNS |
| `http.request` | HTTP requests only |
| `ip.addr == 10.0.0.1` | Traffic to/from a specific host |
| `tcp.flags.syn == 1 && tcp.flags.ack == 0` | TCP SYN packets only |
For substation engineers analyzing IEC 61850 traffic:
| Filter | Matches |
| ----------------- | --------------------------------- |
| `goose` | All GOOSE messages |
| `goose.stNum > 0` | GOOSE messages with state changes |
| `mms` | All MMS traffic |
| `sv` | Sampled Values |
---
## Other clients
Anything that speaks MCP works. The package installs an `mcp-wireshark` binary on `PATH`.
<details>
<summary><b>Claude Desktop</b></summary>
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"wireshark": {
"command": "mcp-wireshark"
}
}
}
```
</details>
<details>
<summary><b>VS Code (Copilot / GitHub Copilot Chat)</b></summary>
Create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"wireshark": {
"command": "mcp-wireshark"
}
}
}
```
</details>
<details>
<summary><b>Cursor / Windsurf / others</b></summary>
Use the same stdio invocation: `command: mcp-wireshark`. No transport flags.
</details>
---
## Prerequisites
- Python **3.10+**
- [Wireshark](https://www.wireshark.org/download.html) installed; `tshark` reachable on `PATH`
Install with `pip` or `uv`:
```bash
pip install mcp-wireshark
# or
uvx mcp-wireshark
```
---
## Troubleshooting
<details>
<summary><b>tshark not found on Windows</b></summary>
Add Wireshark to your **system** `PATH`:
1. Press `Win+R` → run `sysdm.cpl` → **Advanced** → **Environment Variables**
2. Edit `Path` → add `C:\Program Files\Wireshark`
3. Restart your terminal and Claude Code, then re-run `check_installation`
(Avoid passing `PATH` through `claude mcp add --env` — values are taken literally, no `%PATH%` expansion.)
</details>
<details>
<summary><b>Permission denied capturing on Linux</b></summary>
Add yourself to the `wireshark` group, then log out and back in:
```bash
sudo usermod -aG wireshark $USER
```
</details>
<details>
<summary><b>"No packets captured" from live_capture</b></summary>
- Confirm the interface name from `list_interfaces` (Wireshark uses different names than `ifconfig`/`ip`)
- On macOS, you may need to install ChmodBPF (ships with the Wireshark `.dmg`)
- Check that no display filter is excluding everything
</details>
---
## Development
```bash
git clone https://github.com/khuynh22/mcp-wireshark.git
cd mcp-wireshark
python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e ".[dev]"
pytest # tests
black src tests # format
ruff check src tests # lint
mypy src # type check
```
The codebase is organized so new tools land in one of two clearly-scoped files:
- **`src/mcp_wireshark/read_tools.py`** — anything that just inspects state
- **`src/mcp_wireshark/write_tools.py`** — anything that captures traffic or writes files
`server.py` only contains routing. See [CLAUDE.md](CLAUDE.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
Every file path is validated (`..` rejected, extension allow-listed). Every display filter is checked for shell metacharacters. tshark is always invoked via `asyncio.create_subprocess_exec`, never `shell=True`. Hard caps: 10k packets per call, 5 min per live capture. See [SECURITY.md](SECURITY.md).
## License
MIT — see [LICENSE](LICENSE).
TDQS
Scored across 14 tools
Several analysis tools overlap: summarize_pcap, stats_by_proto, and protocol_stats can all produce protocol-hierarchy-style output, and read_pcap vs display_filter are close but distinguishable. The descriptions help guide selection (e.g., prefer summarize_pcap over read_pcap), but stats_by_proto in particular looks like a narrower duplicate of protocol_stats.
Most names follow a verb_noun pattern: follow_tcp, read_pcap, summarize_pcap, decode_protocol, export_json. A few are noun phrases or non-verb-led (stats_by_proto, expert_info, protocol_stats, live_capture), but the overall convention remains readable and predictable.
Fourteen tools is well within the ideal range for a packet-analysis server and covers distinct stages from setup checks and capture to analysis and export. The count is well scoped, even if a couple of analysis tools are redundant.
The surface covers installation checks, interface discovery, live capture, pcap reading/filtering, summaries, protocol statistics, stream following, field decoding, and export. Minor gaps exist, such as detailed single-packet inspection and pcap-to-pcap filtering/merging, but core workflows are covered.