Wireshark Server

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

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

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