# 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