Wireshark MCP Server Container

A containerized Model Context Protocol (MCP) server that provides comprehensive network packet analysis using Wireshark/tshark. Connect it to any MCP-compatible AI client for automated network security analysis, protocol inspection, and traffic forensics.

How It Works: GitHub-Based PCAP Sync

This container does not store PCAP files. Instead, it uses a GitHub repository as the source of truth for your packet captures.

┌──────────────┐       ┌─────────────────────────┐       ┌──────────────────┐
│  Your GitHub │       │  Wireshark MCP Container │       │   AI Client      │
│  Repository  │◄─────►│                          │◄─────►│  (Cursor, etc.)  │
│              │  sync  │  tshark analysis engine  │  MCP  │                  │
│  pcaps/      │       │  /tmp/wireshark_workspace │       │                  │
└──────────────┘       └─────────────────────────┘       └──────────────────┘

The workflow:

1. Store PCAPs in GitHub -- Push .pcap / .pcapng files to any GitHub repo (public or private).

2. Configure credentials -- Provide your GitHub username, PAT, repo URL, and optional path/branch via environment variables or HTTP headers.

3. Sync on demand -- Use wireshark_list_pcaps to see what's available, then wireshark_sync_pcap or wireshark_sync_all_pcaps to pull files into the container's temporary workspace.

4. Analyze -- Run any of the 19 analysis tools against synced PCAPs.

5. Clean up -- Use wireshark_clean_project or let the automatic TTL (default 24h) purge stale workspaces.

This design means the container stays stateless and ephemeral -- PCAP data lives in your GitHub repo, and the container only pulls what it needs for the current analysis session.

Quick Start

Pull from GHCR

docker pull ghcr.io/<your-org>/wireshark-mcp-container:latest

Run with Docker

docker run -d \
  -p 3020:3020 \
  -e DISABLE_JWT_AUTH=true \
  -e GITHUB_USERNAME=your-github-username \
  -e GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx \
  -e GITHUB_REPO=https://github.com/your-org/your-pcap-repo \
  -e GITHUB_PATH=pcaps \
  -e GITHUB_BRANCH=main \
  --name wireshark-mcp \
  ghcr.io/<your-org>/wireshark-mcp-container:latest

Build Locally

docker build -t wireshark-mcp:latest -f dockerfile .

docker run -d \
  -p 3020:3020 \
  --env-file .env \
  --name wireshark-mcp \
  wireshark-mcp:latest

Configuration

All configuration is done through environment variables. See .env.example for a complete reference.

Required

Optional

Passing Credentials via HTTP Headers

Instead of environment variables, credentials can be passed per-request via HTTP headers. This is useful when multiple users share a single server instance:

Headers take precedence over environment variables.

MCP Tools

PCAP Management

Analysis

Protocol Deep-Dives

Security

Typical Analysis Workflow

1. wireshark_list_pcaps          → See what's in your GitHub repo
2. wireshark_sync_pcap           → Pull a capture file into the container
3. wireshark_pcap_triage         → Get an overview and recommendations
4. wireshark_tcp_health          → Drill into TCP issues (if flagged)
5. wireshark_display_filter      → Filter to specific traffic patterns
6. wireshark_follow_stream       → Reconstruct an application conversation
7. wireshark_check_threats       → Check IPs against threat intelligence
8. wireshark_clean_project       → Clean up when done

GitHub Repository Setup for PCAPs

1. Create a GitHub repository (private recommended for sensitive captures).

2. Create a directory for your PCAP files (e.g., pcaps/).

3. Push your .pcap or .pcapng files to that directory.

4. Create a Personal Access Token with repo scope (for private repos) or public_repo scope (for public repos).

5. Configure the container with your repo URL, path, and token.

# Example repo structure
your-pcap-repo/
├── pcaps/
│   ├── incident-2025-01-15.pcap
│   ├── baseline-traffic.pcapng
│   └── suspicious-dns.pcap
└── README.md

Local Development

Prerequisites

• Python 3.11+

• tshark / Wireshark installed

• pip

Setup

pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your GitHub credentials

# Run the server
python server.py

Install tshark

macOS:

brew install wireshark

Ubuntu/Debian:

sudo apt-get install tshark

License

ISC