Skillget

Wireshark-MCP

mcp
SUMMARY

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.

README.md

Wireshark MCP

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.

CI GitHub Release PyPI Python MIT License

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

Install demo video preview

Play or download the install demo video

Analysis Demo

Analysis demo video preview

Play or download the analysis demo video

Installation

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

Install in Cursor

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
  1. Install Python 3.10+.
  2. Install Wireshark and make sure the tshark CLI is available.
  3. 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
  1. Install Python 3.10+.
  2. Install Wireshark or the distro package that provides tshark.
  3. 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
  1. Install Python 3.10+.
  2. Install Wireshark and keep the TShark component enabled in the installer.
  3. 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:

  1. Check the package entrypoint:
wireshark-mcp --version
  1. Verify Python and Wireshark tool discovery:
wireshark-mcp doctor

Automation-friendly form:

wireshark-mcp doctor --format json
  1. Confirm your client targets were detected:
wireshark-mcp clients

Automation-friendly form:

wireshark-mcp clients --format json
  1. 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
  1. 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.

Reviews (0)

No results found