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:

Store PCAPs in GitHub -- Push .pcap / .pcapng files to any GitHub repo (public or private).
Configure credentials -- Provide your GitHub username, PAT, repo URL, and optional path/branch via environment variables or HTTP headers.
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.
Analyze -- Run any of the 19 analysis tools against synced PCAPs.
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

Variable	Description
`GITHUB_USERNAME`	Your GitHub username
`GITHUB_PAT`	GitHub Personal Access Token (needs `repo` scope for private repos)
`GITHUB_REPO`	Full GitHub repo URL (e.g., `https://github.com/org/pcap-repo`)

Optional

Variable	Default	Description
`GITHUB_PATH`	(root)	Subdirectory in the repo where PCAPs are stored
`GITHUB_BRANCH`	`main`	Branch to sync from
`PORT`	`3020`	Server port
`HOST`	`0.0.0.0`	Bind address
`TRANSPORT`	`streamable-http`	MCP transport (`streamable-http` or `stdio`)
`DISABLE_JWT_AUTH`	`true`	Set to `false` to enable Azure AD JWT authentication
`AZURE_AD_TENANT_ID`		Required when JWT auth is enabled
`AZURE_AD_CLIENT_ID`		Optional audience validation when JWT auth is enabled
`ENABLE_AUTH_LOGGING`	`false`	Log user access to tools
`WIRESHARK_PROJECT_TTL`	`86400`	Seconds before stale project workspaces are auto-purged

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:

Header	Maps to
`X-GitHub-Username`	`GITHUB_USERNAME`
`X-GitHub-PAT`	`GITHUB_PAT`
`X-GitHub-Repo`	`GITHUB_REPO`
`X-GitHub-Path`	`GITHUB_PATH`
`X-GitHub-Branch`	`GITHUB_BRANCH`

Headers take precedence over environment variables.

MCP Tools

PCAP Management

Tool	Description
`wireshark_list_pcaps`	List synced and available PCAPs (local + GitHub)
`wireshark_sync_pcap`	Download a single PCAP from GitHub
`wireshark_sync_all_pcaps`	Download all PCAPs from GitHub (skips already-synced)
`wireshark_remove_pcap`	Remove a local PCAP copy
`wireshark_clean_project`	Remove entire project workspace

Analysis

Tool	Description
`wireshark_pcap_triage`	Automated first-pass triage (start here)
`wireshark_analyze_pcap`	Comprehensive packet analysis
`wireshark_protocol_hierarchy`	Protocol distribution breakdown
`wireshark_conversations`	TCP/UDP/IP conversation statistics
`wireshark_display_filter`	Apply Wireshark display filters
`wireshark_follow_stream`	Reconstruct TCP/UDP stream payloads
`wireshark_top_talkers`	Identify highest-volume traffic sources

Protocol Deep-Dives

Tool	Description
`wireshark_tcp_health`	TCP retransmissions, dup ACKs, health scoring
`wireshark_dns_analysis`	DNS queries, NXDOMAIN, tunneling detection
`wireshark_http_summary`	HTTP methods, status codes, response times
`wireshark_tls_analysis`	TLS versions, ciphers, certificate info

Security

Tool	Description
`wireshark_extract_credentials`	Extract plaintext credentials from traffic
`wireshark_check_threats`	Check PCAP IPs against threat intelligence
`wireshark_check_ip_threat`	Check a single IP against threat feeds

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

Create a GitHub repository (private recommended for sensitive captures).
Create a directory for your PCAP files (e.g., pcaps/).
Push your .pcap or .pcapng files to that directory.
Create a Personal Access Token with repo scope (for private repos) or public_repo scope (for public repos).
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

Wireshark MCP Server