wireshark-mcp

English | 简体中文

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:

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.

2. Install this repository

uv sync

3. Generate local config

Run the first-run helper:

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:

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:

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. The recommended command is:

{
  "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
• Full configuration reference: .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.