Content
# Wireshark MCP Server
Network capture and analysis via tshark, exposed as a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server. Gives AI assistants like Claude full access to Wireshark's analysis capabilities.
**20 tools** (15 discrete + 5 composite workflows). Portable — runs on any host with tshark installed. Windows, Linux, macOS.
## What Makes This Different
Most Wireshark MCP servers give you 4-8 basic tools (capture, read, stats). This one includes **composite workflow tools** that chain multiple analyses into a single call:
- **`wireshark_recon`** — Full network survey: protocols, top talkers, device inventory with vendor identification, DNS stats. One call.
- **`wireshark_identify_devices`** — Discovers devices via MAC/OUI resolution, hostname extraction (DNS/mDNS/NBNS), and port-based role classification.
- **`wireshark_traffic_profile`** — Deep dive on a single IP: protocols used, top peers, bytes in/out, active ports, DNS queries, activity over time.
- **`wireshark_security_audit`** — Checks for cleartext credentials (HTTP basic auth, FTP, telnet), unencrypted protocols, DNS anomalies, ARP anomalies, broadcast storms. Optional threat intel via URLhaus.
- **`wireshark_compare_captures`** — Diff two captures: new/disappeared devices, protocol distribution changes, traffic volume deltas.
Plus a bundled **OUI database** (~1500 vendor prefixes) for instant MAC-to-vendor resolution without external lookups.
## Quick Start
### Prerequisites
- Python 3.11+
- [Wireshark](https://www.wireshark.org/download.html) installed (tshark is included)
- On Linux: capture permissions (`sudo setcap cap_net_raw+ep $(which tshark)` or run as root)
### Install
```bash
git clone https://github.com/wgthomas/wireshark-mcp.git
cd wireshark-mcp
pip install -r requirements.txt
```
### Configure Claude Code / Claude Desktop
Add to your MCP config (`~/.claude.json` or Claude Desktop settings):
```json
{
"mcpServers": {
"wireshark": {
"command": "python",
"args": ["/path/to/wireshark-mcp/wireshark_mcp.py"],
"env": {}
}
}
}
```
tshark is auto-detected. If it's not on your PATH, set `WIRESHARK_TSHARK_PATH`:
```json
"env": {
"WIRESHARK_TSHARK_PATH": "/usr/bin/tshark"
}
```
## Tools
### Discrete Tools (15)
| Tool | Description |
|------|-------------|
| `wireshark_list_interfaces` | Available capture interfaces |
| `wireshark_check_permissions` | Verify tshark and capture privileges |
| `wireshark_capture` | Live capture to pcapng file |
| `wireshark_list_captures` | Saved capture files |
| `wireshark_protocol_hierarchy` | Protocol distribution tree |
| `wireshark_conversations` | Who's talking to whom (top N by bytes) |
| `wireshark_endpoints` | Unique endpoints with traffic volumes |
| `wireshark_dns_analysis` | DNS query types, response codes, response times |
| `wireshark_io_stats` | Traffic volume over time intervals |
| `wireshark_http_analysis` | HTTP methods and response codes |
| `wireshark_expert_info` | Wireshark warnings, errors, and notes |
| `wireshark_extract_fields` | Custom tshark field extraction |
| `wireshark_packet_list` | First N packets summary |
| `wireshark_resolve_oui` | MAC address vendor lookup |
| `wireshark_version` | tshark version and path |
### Workflow Tools (5)
| Tool | Description |
|------|-------------|
| `wireshark_recon` | Full network reconnaissance |
| `wireshark_identify_devices` | Device discovery and classification |
| `wireshark_traffic_profile` | Single IP deep dive |
| `wireshark_security_audit` | Security-focused analysis |
| `wireshark_compare_captures` | Diff two capture files |
All workflow tools accept either a `pcap_file` path or an `interface` for live capture.
## Configuration
All settings via environment variables with `WIRESHARK_` prefix:
| Variable | Default | Description |
|----------|---------|-------------|
| `WIRESHARK_TSHARK_PATH` | Auto-detected | Path to tshark binary |
| `WIRESHARK_CAPTURE_DIR` | `./captures` | Where to save captures |
| `WIRESHARK_DEFAULT_DURATION` | `120` | Capture duration (seconds) |
| `WIRESHARK_MAX_PACKETS` | `100000` | Max packets per capture |
| `WIRESHARK_DEFAULT_TOP_N` | `20` | Default limit for ranked results |
## Token Optimization
All tools return structured JSON, never raw tshark text. Outputs are aggregated summaries capped at ~4000 tokens. Use `wireshark_extract_fields` for targeted deep dives when you need specific packet data.
## Security
- **No shell=True** — All tshark commands use `subprocess` with argument lists
- **Input sanitization** — Display filters and parameters are validated against injection characters
- **Capture files only** — The server reads/writes pcap files, never executes arbitrary commands
## Testing
```bash
# Basic tests (no capture file needed)
python test_quick.py
# Full tests with a capture file
python test_quick.py path/to/capture.pcapng
# Workflow tests
python test_workflows.py path/to/capture.pcapng [target_ip]
```
## License
MIT
