English | [简体中文](README.zh-CN.md)

# wiresharkmcp

`wiresharkmcp` is a standalone MCP server that exposes Wireshark CLI tools to AI agents through MCP tools, resources, and prompts.

## Usage Video

A short walkthrough of the repository setup and usage:

<div align="center">
  <img src="assets/demo.gif" width="960" />
</div>

## 5-Minute Setup

### 1. Install Wireshark CLI

macOS:

1. Install the official Wireshark `.dmg`.
2. Move `Wireshark.app` to `/Applications`.
3. Install `ChmodBPF` from the same `.dmg`.

Ubuntu/Debian:

```bash
sudo apt update
sudo apt install wireshark-common tshark
```

If you use another distro, need `dftest`, or want a source build, use the advanced guide in [docs/advanced-install.md](docs/advanced-install.md).

### 2. Install this repository

```bash
uv sync
```

### 3. Generate local config

Run the first-run helper:

```bash
uv run python scripts/doctor.py
```

It prints:

- your current platform and detected Wireshark binaries
- a suggested `.env` with absolute binary paths and a home-directory `WIRESHARK_MCP_ALLOWED_ROOTS`
- a suggested stdio `mcpServers` JSON block

If you want it to create `.env` for you:

```bash
uv run python scripts/doctor.py --write-env
```

Status meanings:

- `usable`: all core Wireshark binaries and `dftest` were found
- `usable but degraded`: core binaries were found, but `dftest` is missing
- `not ready`: one or more core binaries are still missing

Minimal `.env` shape:

```env
WIRESHARK_MCP_ALLOWED_ROOTS=["/absolute/path/to/wireshark-mcp"]
WIRESHARK_MCP_TRANSPORT=stdio
```

`doctor.py` also fills any detected `WIRESHARK_MCP_*_PATH` entries with absolute paths so GUI clients do not depend on your shell `PATH`.

### 4. Paste the MCP config into your client and validate

Copy the `Suggested MCP config` block printed by `doctor.py`, or start from [examples/mcp.json](examples/mcp.json). The recommended command is:

```json
{
  "mcpServers": {
    "wireshark-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/wiresharkmcp-public",
        "wireshark-mcp"
      ],
      "env": {
        "WIRESHARK_MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

Then connect your MCP client and call `ws_runtime_info`. That one tool is the only required first-run validation step. It tells you:

- which Wireshark binaries were found
- which features are currently available
- which filesystem roots the server can access

## What the First-Run Helper Optimizes

- It prefers explicit absolute binary paths over `PATH`, which is more reliable for desktop and GUI MCP clients.
- On macOS it checks `/Applications/Wireshark.app/Contents/MacOS` first.
- On Linux it checks `PATH` and common locations such as `/usr/bin`.
- It refuses to overwrite an existing `.env`; if you already have one, it tells you to merge changes manually.

## Advanced Docs

- Advanced install, source builds, and Linux packaging notes: [docs/advanced-install.md](docs/advanced-install.md)
- Full configuration reference: [.env.example](.env.example)

## Security

- The server only reads and writes files inside `WIRESHARK_MCP_ALLOWED_ROOTS`.
- Do not commit `.env`, capture files, or generated logs from real environments.

## License

MIT. See [LICENSE](LICENSE).