🔒

io.github.bx33661/wireshark-mcp

Professional network analysis with tshark. Security audits, deep-dives, and threat detection.

0 installs

Trust: 37 — Low

Security

Ask AI about io.github.bx33661/wireshark-mcp

I know everything about io.github.bx33661/wireshark-mcp. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Wireshark MCP

Give your AI assistant a packet analyzer.
Drop a .pcap file, ask questions in plain English — get answers backed by real tshark data.

English · 中文 · Changelog · Contributing

What is this?

Wireshark MCP is an MCP Server that turns tshark into a structured analysis interface, then layers in optional Wireshark suite utilities such as capinfos, mergecap, editcap, dumpcap, and text2pcap when they are available. The result is a packet-analysis server that still works with only tshark, but gets stronger automatically on hosts with more of the Wireshark toolchain installed.

You:    "Find all DNS queries going to suspicious domains in this capture."
Claude: [calls wireshark_extract_dns_queries → wireshark_check_threats]
        "Found 3 queries to domains flagged by URLhaus: ..."

Prerequisites

Python 3.10+
Wireshark installed with tshark
tshark is the only required Wireshark CLI dependency
Optional suite tools such as capinfos, mergecap, editcap, dumpcap, and text2pcap are auto-detected and enable extra MCP features when present
Live capture prefers dumpcap when available, but falls back to tshark so a minimal installation still works
tshark on your PATH is recommended, but wireshark-mcp install also records detected absolute Wireshark tool paths for GUI clients
Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, etc.

1.0 Support Matrix

For v1.0, "stable" means the project commits to the following baseline:

Area	v1.0 baseline
Operating systems	Windows, Linux, and macOS
CI validation	Test suite runs on all three platforms; packaged CLI smoke tests run on all three platforms; real `tshark` integration smoke runs on Linux
Python versions	3.10, 3.11, 3.12, 3.13
Required Wireshark dependency	`tshark`
Optional Wireshark suite tools	`capinfos`, `mergecap`, `editcap`, `dumpcap`, `text2pcap` auto-detected when present
Supported install paths	`pip install wireshark-mcp`, source install, and manual MCP config snippets
User-facing verification	`wireshark-mcp doctor`, `wireshark-mcp clients`, and `wireshark-mcp config`

If one of these baseline items stops working, that is a 1.0.x bug, not a "future enhancement".

Demo Videos

Install Demo

Play or download the install demo video

Analysis Demo

Play or download the analysis demo video

Installation

Option 1 — One-click install in Cursor (no pre-install needed)

Requires uv and Wireshark to be installed on your system.

Option 2 — pip install + auto-configure

pip install wireshark-mcp

Then auto-configure all your MCP clients in one command:

wireshark-mcp install

That's it — restart your AI client and you're ready to go. 🎉

If anything still looks off, run:

wireshark-mcp doctor

What does install do? It scans your system for known MCP client config files (Claude, Cursor, VS Code, etc.) and injects the wireshark-mcp server entry. Existing settings are preserved. See Supported Clients for the full list.

Install from source

pip install git+https://github.com/bx33661/Wireshark-MCP.git
wireshark-mcp install

Uninstall from all clients

wireshark-mcp uninstall

Hosted deployment

A hosted deployment is available on Fronteir AI.

Platform Setup

Use this section when you want the shortest reliable path to a working setup on each OS.

macOS

Install Python 3.10+.
Install Wireshark and make sure the tshark CLI is available.
Install the package:

pip install wireshark-mcp
wireshark-mcp install
wireshark-mcp doctor

If you plan to use live capture, dumpcap is preferred when available.

Linux

Install Python 3.10+.
Install Wireshark or the distro package that provides tshark.
Install the package:

pip install wireshark-mcp
wireshark-mcp install
wireshark-mcp doctor

Live capture may require extra capture permissions depending on your distro. Offline .pcap analysis works as soon as tshark is available.

Windows

Install Python 3.10+.
Install Wireshark and keep the TShark component enabled in the installer.
In PowerShell or Command Prompt, run:

py -m pip install wireshark-mcp
wireshark-mcp install
wireshark-mcp doctor

The installer writes absolute Python and Wireshark tool paths for GUI MCP clients, which is especially helpful on Windows where GUI apps often do not inherit your shell environment.

Supported Clients

wireshark-mcp install auto-configures the following clients across macOS, Linux, and Windows:

Client	Config File
Claude Desktop	`claude_desktop_config.json`
Claude Code	`~/.claude.json`
Cursor	`~/.cursor/mcp.json`
VS Code	`settings.json` (via `mcp.servers`)
VS Code Insiders	`settings.json` (via `mcp.servers`)
Windsurf	`mcp_config.json`
Cline	`cline_mcp_settings.json`
Roo Code	`mcp_settings.json`
Kilo Code	`mcp_settings.json`
Antigravity IDE	`mcp_config.json`
Zed	`settings.json` (via `mcp.servers`)
LM Studio	`mcp.json`
Warp	`mcp_config.json`
Trae	`mcp_config.json`
Gemini CLI	`settings.json`
Copilot CLI	`mcp-config.json`
Amazon Q	`mcp_config.json`
Codex	`config.toml`

For unsupported clients, run wireshark-mcp config to get the JSON snippet and paste it manually.

Configuration

Recommended: Auto-Configuration (one command)

pip install wireshark-mcp
wireshark-mcp install

This detects all installed MCP clients and writes the config automatically. Existing settings are preserved. The generated entry always uses the current Python interpreter (python -u -m wireshark_mcp.server), forwards your current PATH, and stores detected absolute Wireshark tool paths when available, so GUI MCP clients do not need wireshark-mcp or tshark to be discoverable on their own.

⚠️ Restart your MCP client after running install for changes to take effect. 🔎 If analysis tools still fail to launch, run wireshark-mcp doctor to verify Python, required vs optional Wireshark CLI tools, and client config detection.

Manual Configuration

If you prefer to configure manually, start with:

wireshark-mcp config

If you use Codex:

wireshark-mcp config --format codex-toml

Detailed client-by-client instructions now live in docs/manual-configuration.md, including Claude Desktop, Claude Code, Cursor, VS Code, Codex, generic JSON-based clients, and Docker / SSE mode.

5-Minute Verification

After installation, this is the fastest way to confirm the setup is actually production-usable:

Check the package entrypoint:

wireshark-mcp --version

Verify Python and Wireshark tool discovery:

wireshark-mcp doctor

Automation-friendly form:

wireshark-mcp doctor --format json

Confirm your client targets were detected:

wireshark-mcp clients

Automation-friendly form:

wireshark-mcp clients --format json

Print the exact manual config for the current machine:

wireshark-mcp config

If you use Codex specifically, you can also render TOML directly:

wireshark-mcp config --format codex-toml

Open your MCP client, attach a small .pcap, and run:

Use wireshark_open_file on this capture, summarize the protocols you see, then run wireshark_quick_analysis.

If all five checks work, the install is in the expected v1.0 steady state.

Operational Docs

Detailed steady-state and release docs now live under docs/:

Quick Start

Paste this into your AI client after pointing it at a pcap file:

Analyze <path/to/file.pcap> using the Wireshark MCP tools.

- Start with wireshark_open_file to get capture-wide context and recommended tools.
- Use wireshark_security_audit for a one-call security analysis.
- Or use wireshark_quick_analysis for a fast traffic overview.
- Drill into details with wireshark_follow_stream or wireshark_get_packet_details.
- Never guess — always verify with tools.
- Write findings to report.md.

Bundled Codex Skill

This repo also includes a Codex skill at skills/wireshark-traffic-analysis/. It is designed for disciplined packet analysis: start with capture-wide context, choose the right workflow, validate with packet evidence, and finish with actionable next steps. The latest revision is also grounded in official Wireshark documentation for protocol hierarchy, endpoints, conversations, expert info, display filters, and stream-follow behavior. For cross-app discovery, the same skill is mirrored into .github/skills/ and .claude/skills/, with root instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), GitHub Copilot instructions, and a machine-readable catalog at skills/manifest.json.

The skill supports these modes:

triage
security
incident-response
troubleshoot
ctf

Example invocation:

Use $wireshark-traffic-analysis to investigate <file.pcap>.
Start in triage mode, escalate if you find suspicious behavior, and produce a concise report with exact filters, streams, frames, confidence, and next steps.

Compatibility Policy

The stable CLI for 1.x is the subcommand interface: serve, install, uninstall, doctor, config, clients.
Legacy flags such as --install, --doctor, and --config remain supported throughout 1.x.
wireshark_read_packets remains available throughout 1.x for backwards compatibility, but it is deprecated and not recommended for new workflows.
New packet-inspection workflows should use wireshark_get_packet_list and wireshark_get_packet_details.

Prompt Engineering

LLMs perform best when you tell them to:

start with wireshark_open_file
use agentic tools first, then drill down
verify instead of guessing
produce a structured report

Ready-to-paste prompt templates for security audits, CTF work, and performance troubleshooting now live in docs/prompt-engineering.md.

Tools

⚡ Agentic Workflows — one-call comprehensive analysis

Tool	Description
`wireshark_security_audit`	One-call security audit: 8-phase analysis (threat intel, credential scan, port scan, DNS tunnel, cleartext, anomalies) with risk scoring (0-100) and recommendations
`wireshark_quick_analysis`	One-call traffic overview: file info, protocol distribution, top talkers, conversations, hostnames, anomaly summary, suggested next steps
`wireshark_open_file`	Smart file opener: analyzes pcap content and recommends the most relevant tools while keeping the MCP tool surface stable
`wireshark_get_capabilities`	Toolchain capability report: required, recommended, and optional Wireshark suite tools visible to the current MCP server

💡 These tools replace the need to manually chain 5-10 tool calls. Just call one and get a complete report.

Packet Analysis — inspect, navigate, and search packets

Tool	Description
`wireshark_get_packet_list`	Paginated packet list with display filter and custom column support
`wireshark_get_packet_details`	Full JSON dissection of a single frame, with optional layer filtering to cut token usage
`wireshark_get_packet_bytes`	Raw Hex + ASCII dump (Wireshark's "Packet Bytes" pane)
`wireshark_get_packet_context`	View N packets before and after a frame for contextual debugging
`wireshark_read_packets`	Deprecated compatibility tool retained for `1.x`; prefer `wireshark_get_packet_list` and `wireshark_get_packet_details`
`wireshark_follow_stream`	Reassemble a full TCP / UDP / HTTP stream with pagination and search
`wireshark_search_packets`	Pattern search across raw bytes or decoded fields (Regex supported)

Data Extraction — pull structured data from captures

Tool	Description
`wireshark_extract_fields`	Extract any tshark fields as a table
`wireshark_extract_http_requests`	HTTP method, URI, and host for every request
`wireshark_extract_dns_queries`	All DNS queries in the capture
`wireshark_list_ips`	All unique source, destination, or both IP addresses
`wireshark_export_objects`	Extract embedded files (HTTP, SMB, TFTP, etc.)
`wireshark_verify_ssl_decryption`	Confirm TLS decryption using a keylog file

Statistics — traffic patterns and anomaly detection

Tool	Description
`wireshark_stats_protocol_hierarchy`	Protocol Hierarchy Statistics — see what protocols dominate
`wireshark_stats_endpoints`	All endpoints sorted by traffic volume
`wireshark_stats_conversations`	Communication pairs with byte/packet counts
`wireshark_stats_io_graph`	Traffic volume over time (spot DDoS, scans, bursts)
`wireshark_stats_expert_info`	Wireshark's expert analysis: errors, warnings, notes
`wireshark_stats_service_response_time`	SRT stats for HTTP, DNS, and other protocols

File Operations & Live Capture

Tool	Description
`wireshark_get_file_info`	File metadata via `capinfos` (duration, packet count, link type)
`wireshark_merge_pcaps`	Merge multiple captures into one file
`wireshark_filter_save`	Apply a display filter and save matching packets to a new file
`wireshark_list_interfaces`	List available network interfaces
`wireshark_capture`	Start a live capture (duration, packet count, BPF filter, ring buffer)

Suite Utilities — optional Wireshark companion tools

These tools are additive. The server still starts with only tshark, and only advertises or uses the extra workflows below when the corresponding Wireshark companion binaries are present.

Tool	Description
`wireshark_editcap_trim`	Trim a capture to a timestamp window using `editcap`
`wireshark_editcap_split`	Split a capture by packet count or interval using `editcap`
`wireshark_editcap_time_shift`	Shift packet timestamps by a relative offset using `editcap`
`wireshark_editcap_deduplicate`	Remove duplicate packets using `editcap`'s duplicate window
`wireshark_text2pcap_import`	Convert ASCII or hex dumps into capture files using `text2pcap`

Security Analysis

Tool	Description
`wireshark_check_threats`	Cross-reference captured URLs and hostnames against URLhaus threat intelligence
`wireshark_extract_credentials`	Detect plaintext credentials in HTTP Basic Auth, FTP, and Telnet
`wireshark_detect_port_scan`	Detect SYN, FIN, NULL, and Xmas port scans with configurable threshold
`wireshark_detect_dns_tunnel`	Detect DNS tunneling (long queries, TXT abuse, subdomain entropy)
`wireshark_detect_dos_attack`	Detect DoS/DDoS patterns (SYN flood, ICMP/UDP flood, DNS amplification)
`wireshark_analyze_suspicious_traffic`	Comprehensive anomaly analysis: cleartext protocols, unusual ports, expert warnings

Protocol Deep Dive — TLS, TCP, ARP, SMTP, DHCP analysis

Tool	Description
`wireshark_extract_tls_handshakes`	TLS version, cipher suite, SNI, and certificate info from Client/Server Hello
`wireshark_analyze_tcp_health`	TCP retransmissions, duplicate ACKs, zero window, resets, out-of-order analysis
`wireshark_detect_arp_spoofing`	ARP spoofing detection: IP-MAC conflicts, gratuitous ARP floods
`wireshark_extract_smtp_emails`	SMTP email metadata: sender, recipient, mail server info
`wireshark_extract_dhcp_info`	DHCP lease information: assigned IPs, hostnames, DNS servers

Decoding & Visualization

Tool	Description
`wireshark_decode_payload`	Auto-detect and decode Base64, Hex, URL encoding, Gzip, Deflate, Rot13, and more
`wireshark_plot_traffic`	ASCII bar chart of traffic over time — spot DDoS or scan patterns instantly
`wireshark_plot_protocols`	ASCII protocol tree — visual overview of what's in the capture

Note: Security, Protocol, and Threat tools stay available for the whole session. wireshark_open_file recommends which ones are most relevant for the current capture.

MCP Resources

Resource URI	Description
`wireshark://reference/display-filters`	Complete display filter syntax cheatsheet with common examples
`wireshark://reference/protocol-fields`	Protocol field name reference for filters and extraction
`wireshark://guide/usage`	Recommended analysis workflows and tips
`wireshark://capabilities`	Current required, recommended, and optional Wireshark suite capabilities

MCP Prompts

Prompt	Description
`security_audit`	Full security audit workflow: threat intel, credential scan, attack detection
`performance_analysis`	Network performance analysis: TCP health, response times, bottlenecks
`ctf_solve`	CTF challenge solver: flag search, stream analysis, steganography checks
`incident_response`	IR workflow: triage, IOC extraction, attack timeline, containment
`traffic_overview`	Quick traffic summary with protocol breakdown and visualization

Why Wireshark MCP?

There are other network analysis MCP servers out there, but Wireshark MCP was built with a few core goals:

Feature	Wireshark MCP	Others
One-command install (`install`)	✅	❌
Agentic workflows (one-call security audit)	✅	❌
Capture-aware recommendations with stable tool surface	✅	❌
40+ specialized analysis tools	✅	5-10
Threat intelligence integration	✅	❌
Smart Python env detection	✅	❌
18+ MCP client support	✅	Manual

Troubleshooting

Symptom	What it usually means	What to do
`tshark` is missing in `doctor`	Wireshark or the CLI component is not installed, or the path is not discoverable	Install Wireshark with `tshark`, then rerun `wireshark-mcp doctor`
MCP client sees the server but tool calls fail to launch	The GUI client is missing runtime env vars or absolute tool paths	Rerun `wireshark-mcp install`, restart the client, then rerun `wireshark-mcp doctor`
Live capture fails but offline `.pcap` analysis works	Capture permissions or `dumpcap` availability are the issue, not the core server	Use offline capture files first; if you need live capture, grant the required OS-specific capture permissions
`capinfos`, `editcap`, or `text2pcap` are missing	Optional Wireshark suite tools are not installed	This is not fatal; the server still works with `tshark`, but those extra workflows stay unavailable
Your client is not in the supported list	Auto-install only covers known config formats	Run `wireshark-mcp config` or `wireshark-mcp config --format codex-toml` and paste the output manually

Development

Install dev dependencies:

pip install -e ".[dev]"

Test with the MCP Inspector (opens a local web UI to call tools interactively):

npx -y @modelcontextprotocol/inspector uv run wireshark-mcp

Run the test suite:

uv run python -m pytest tests/ -v

Lint & type check:

uv run python -m ruff check src/ tests/
uv run python -m mypy --package wireshark_mcp --ignore-missing-imports --no-namespace-packages

Docker:

docker compose up -d
# Pcap files go in ./pcaps/ (mounted as /data)

CLI options:

wireshark-mcp                          # Start the stdio MCP server
wireshark-mcp serve --transport sse --host 0.0.0.0 --port 8080
wireshark-mcp install                  # Auto-configure all detected MCP clients
wireshark-mcp install --client codex   # Target a specific client
wireshark-mcp uninstall
wireshark-mcp doctor                   # Human-readable diagnostics
wireshark-mcp doctor --format json     # Machine-readable diagnostics
wireshark-mcp clients                  # Human-readable client detection
wireshark-mcp clients --format json    # Machine-readable client detection
wireshark-mcp config                   # Print JSON config for manual setup
wireshark-mcp config --format codex-toml
wireshark-mcp --version

Legacy flags such as --install, --doctor, and --config remain supported for backwards compatibility.

See CONTRIBUTING.md for the full development setup guide.

_{MIT License · Report a Bug}