# Wireshark MCP Server

Packet capture and analysis for AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP).

Works with **any stdio MCP host**: Cursor, Claude Desktop, Claude Code, VS Code / Copilot, Windsurf, custom agents, and similar tools. No vendor lock-in — the host only needs to launch:

```text
python -m wireshark_mcp
```

**Version 0.2.2**

| Docs (wiki) | |
|-------------|--|
| [Setup for novices](docs/Setup.md) | Install TShark + this package |
| [MCP clients](docs/Clients.md) | Cursor, Claude, VS Code, generic |
| [Troubleshooting](docs/Troubleshooting.md) | Offline server, PATH issues |
| [Security](docs/Security.md) | Safe capture rules |

GitHub Pages (optional): set **Settings → Pages → Source = GitHub Actions**, then the `Pages` workflow publishes `docs/` as HTML.

## What you get

- Live capture and pcap/pcapng analysis through MCP **tools**
- Guided workflows via MCP **prompts**
- Startup **preflight**: if TShark is missing, the process exits so your host shows the server offline/error instead of a broken tool list
- `setup` / `doctor` CLIs so a new user can configure paths without guessing

## Requirements

- Python **3.10+**
- [TShark](https://www.wireshark.org/download.html) (`PATH` or `TSHARK_PATH`)
- [Npcap](https://npcap.com/#download) (Windows) or libpcap (Unix) for **live** capture
- Authorization to capture on the target network

## Quick start (5 minutes)

```bash
git clone https://github.com/A-G-U-P-T-A/wireshark-mcp
cd wireshark-mcp
python -m venv .venv

# Windows:  .venv\Scripts\activate
# Unix:     source .venv/bin/activate

python -m pip install -e .
python -m wireshark_mcp doctor
python -m wireshark_mcp setup
```

`setup` detects TShark (or asks for its path) and writes or prints a standard `mcpServers` JSON block. Point your host at that config, then **reload / restart** the host.

Windows Wireshark install:

```bash
winget install --id WiresharkFoundation.Wireshark -e
```

## MCP config (any host)

```json
{
  "mcpServers": {
    "wireshark": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "wireshark_mcp"],
      "env": {
        "TSHARK_PATH": "/absolute/path/to/tshark"
      }
    }
  }
}
```

Windows example paths:

- Python: `C:\\Users\\YOU\\...\\wireshark-mcp\\.venv\\Scripts\\python.exe`
- TShark: `C:\\Program Files\\Wireshark\\tshark.exe`

Ready-made template: [`examples/mcpServers.wireshark.json`](examples/mcpServers.wireshark.json)  
Client-specific file locations: [`docs/Clients.md`](docs/Clients.md)

### CLI

| Command | Purpose |
|---------|---------|
| `python -m wireshark_mcp` | Run the MCP server (stdio) |
| `python -m wireshark_mcp doctor` | JSON dependency report (exit 0/1) |
| `python -m wireshark_mcp setup` | Interactive TShark + host config |
| `python -m wireshark_mcp setup --client print` | Print JSON only |

## Project layout

```text
src/wireshark_mcp/     # MCP server package (tools, prompts, preflight)
examples/              # Sample mcpServers JSON
docs/                  # Setup wiki for novices
tests/                 # pytest (no live capture by default)
.cursor/skills/        # Optional Cursor agent skill
pyshark_mcp.py         # Thin legacy shim
```

## Tools (selected)

| Area | Tools |
|------|--------|
| Setup | `check_environment`, `configure_tshark` |
| Capture | `list_interfaces`, `quick_capture`, `capture_live_packets`, `save_capture_to_file` |
| Analysis | `read_pcap_file`, `analyze_traffic`, `deep_packet_analysis`, `quick_traffic_analysis` |
| App protocols | `analyze_dns_traffic`, `analyze_http_traffic`, `analyze_http_traffic_tabular` |
| Diagnostics | `protocol_hierarchy_statistics`, `expert_information`, `filtered_packet_display` |

## Prompts & resources

**Prompts:** `packet_capture_help`, `investigate_live_traffic`, `analyze_pcap_file`, `security_traffic_review`, `safe_capture_rules`

**Resources:** `pyshark://version`, `pyshark://config` (`allow_simulation` is always `false`)

## Security

- Interfaces allowlisted from `tshark -D`; shell metacharacters rejected
- Subprocesses use argv + `shell=False`
- Failures return errors — **no simulated packets**

Details: [docs/Security.md](docs/Security.md)

## Tests & CI

```bash
python -m pip install -e ".[dev]"
pytest -q -m "not live"
```

GitHub Actions installs TShark on Ubuntu and runs the non-live suite.

## License

MIT