Content
# WiresharkMCP
A [Model Context Protocol](https://modelcontextprotocol.io) server, written in Rust,
that exposes Wireshark's command-line tools (`tshark`, `dumpcap`, `capinfos`) as MCP
tools for network capture analysis and live sniffing.
It speaks MCP over stdio (newline-delimited JSON-RPC 2.0) and has **no runtime
dependencies beyond a Wireshark install** — the only crate it pulls in is `serde_json`.
## Requirements
- Rust / Cargo (1.75+) — https://rustup.rs
- Wireshark with its CLI tools installed
- **macOS:** install [Wireshark.app](https://www.wireshark.org/download.html); the tools live in `/Applications/Wireshark.app/Contents/MacOS/`
- **Debian/Ubuntu:** `sudo apt install tshark`
- **Fedora/RHEL:** `sudo dnf install wireshark-cli`
- **Windows:** install Wireshark; ensure `tshark.exe` is on `PATH`
The server auto-detects the CLI location. Override with the `WIRESHARK_BIN_DIR`
environment variable when needed. Detection order: `WIRESHARK_BIN_DIR` →
macOS app bundle → `/opt/homebrew/bin` → `/usr/local/bin` → `/usr/bin`.
---
## Quick start (automated)
Clone, build, and register the server with every MCP client detected on your
machine in one step:
```sh
git clone https://github.com/JoasASantos/WiresharkMCP.git
cd WiresharkMCP
./install.sh
```
`install.sh` will:
1. Verify Cargo and Wireshark are present (and locate `tshark`).
2. Build the release binary (`target/release/wireshark-mcp`).
3. Auto-detect and configure any of: **Claude Desktop**, **Claude Code**,
**Cursor**, **Cline (VS Code)**, **Windsurf**.
4. Print a ready-to-paste JSON block for any other MCP client.
Re-run it any time — it updates existing entries in place and never duplicates them.
---
## Manual setup per client
First build the binary and note its absolute path:
```sh
cargo build --release
echo "$(pwd)/target/release/wireshark-mcp"
```
Use that path (referred to below as `<BINARY>`) in each config.
### Claude Desktop
Edit the config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"wireshark": {
"command": "<BINARY>",
"env": { "WIRESHARK_BIN_DIR": "/Applications/Wireshark.app/Contents/MacOS" }
}
}
}
```
Restart Claude Desktop afterwards.
### Claude Code (CLI)
```sh
# user scope (available in every project)
claude mcp add wireshark --scope user -- <BINARY>
# or project scope (writes .mcp.json in the current repo)
claude mcp add wireshark -- <BINARY>
```
Verify:
```sh
claude mcp list
```
### Cursor
Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
```json
{
"mcpServers": {
"wireshark": { "command": "<BINARY>" }
}
}
```
### Cline / Roo Code (VS Code)
Open the Cline MCP settings (`cline_mcp_settings.json`) and add:
```json
{
"mcpServers": {
"wireshark": { "command": "<BINARY>", "disabled": false }
}
}
```
### Windsurf
Edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"wireshark": { "command": "<BINARY>" }
}
}
```
### Any other MCP client
The server is a plain stdio JSON-RPC 2.0 process. Point the client at the
binary with no arguments:
```json
{
"command": "<BINARY>",
"args": [],
"env": { "WIRESHARK_BIN_DIR": "/path/to/wireshark/bin" }
}
```
---
## Tools
| Tool | What it does | tshark equivalent |
|------|--------------|-------------------|
| `list_interfaces` | Enumerate capture interfaces | `tshark -D` |
| `capture_info` | File summary: packets, duration, rates, encapsulation | `capinfos <file>` |
| `read_packets` | Packet summaries or extracted fields, with display filter/count | `tshark -r -Y -c [-T fields -e …]` |
| `packet_details` | Full dissection tree for matching packets | `tshark -r -Y -c -V` |
| `protocol_hierarchy` | Protocol breakdown by frames/bytes | `tshark -z io,phs` |
| `conversations` | Endpoint-to-endpoint conversation stats | `tshark -z conv,<proto>` |
| `endpoints` | Per-host traffic stats | `tshark -z endpoints,<proto>` |
| `follow_stream` | Reassemble a TCP/UDP/HTTP/TLS stream | `tshark -z follow,…` |
| `expert_info` | Dissector warnings/errors/notes | `tshark -z expert` |
| `io_statistics` | Time-bucketed frames/bytes | `tshark -z io,stat,<interval>` |
| `live_capture` | Bounded live sniff (duration/packet cap), optional save | `tshark -i -a duration:N …` |
### Example prompts
- *"List my capture interfaces."*
- *"Summarize `/tmp/session.pcapng` and show the protocol hierarchy."*
- *"From `capture.pcap`, show all packets where `http.request` and extract the host and URI fields."*
- *"Follow TCP stream 3 in `capture.pcap`."*
- *"Sniff en0 for 10 seconds filtering `tcp port 443` and save to `/tmp/tls.pcapng`."*
---
## Safety notes
- **No shell.** Filters and paths are passed as discrete `argv` entries via
`std::process::Command`, so display/capture filters cannot inject shell commands.
- **Bounded captures.** `live_capture` always requires an interface and clamps
duration to ≤ 300 s; combine with `max_packets` for tighter bounds.
- **Name resolution off by default.** tshark runs with `-n` unless
`resolve_names: true`, keeping analysis deterministic and avoiding outbound
DNS/OUI lookups.
- **Privileges.** Live capture needs packet-capture permission (ChmodBPF on macOS,
`CAP_NET_RAW` / the `wireshark` group on Linux). Reading existing files needs none.
- Output is truncated at 60 KB per call; narrow the filter or lower the count for
large captures.
---
## Development
```sh
cargo build --release # build
cargo fmt # format
./scripts/smoke-test.sh # drive the server over stdio with sample JSON-RPC
```
### Layout
```
src/
main.rs # stdio JSON-RPC loop + request routing
protocol.rs # JSON-RPC 2.0 response helpers
wireshark.rs # tool discovery + subprocess execution
tools.rs # MCP tool catalog, schemas, and dispatch
install.sh # build + auto-configure detected MCP clients
```
## License
MIT
