wireshark-mcp 0.6.0

A production-grade Model Context Protocol (MCP) server for Wireshark

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 wraps tshark into structured tools, letting AI assistants like Claude or Cursor perform deep packet analysis without you touching the command line.

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 available in your PATH
• Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, etc.

---

Installation

pip install wireshark-mcp

Install from source

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

---

Configuration

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wireshark": {
      "command": "uv",
      "args": ["tool", "run", "wireshark-mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add wireshark -- uv tool run wireshark-mcp

Or edit ~/.claude/claude_desktop_config.json with the same JSON format above.

Cursor

Go to Settings → Features → MCP Servers → Add new MCP server:

• Name: wireshark
• Type: command
• Command: uv tool run wireshark-mcp

Or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "wireshark": {
      "command": "uv",
      "args": ["tool", "run", "wireshark-mcp"]
    }
  }
}

OpenAI Codex CLI

codex mcp add wireshark -- uv tool run wireshark-mcp

Or edit ~/.codex/config.toml:

[mcp_servers.wireshark]
command = "uv"
args = ["tool", "run", "wireshark-mcp"]

Trae AI IDE

Go to Settings → MCP → Add MCP Server → Manual, then paste:

{
  "mcpServers": {
    "wireshark": {
      "command": "uv",
      "args": ["tool", "run", "wireshark-mcp"]
    }
  }
}

Or edit .trae/mcp.json in your project root.

Docker / SSE mode: docker compose up -d then point your client to http://localhost:8080/sse

---

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 load the file and activate relevant 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.

---

Tools

⚡ Agentic Workflows — one-call comprehensive analysis (NEW in v0.6)

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 dynamically activates protocol-specific tools (Progressive Discovery)

💡 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_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)

Security Analysis

Tool	Description
wireshark_check_threats	Cross-reference captured IPs 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 are contextual — they activate automatically when you call wireshark_open_file. The Agentic tools (security_audit, quick_analysis) are always available.

---

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

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

---

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:

pytest tests/ -v

Lint & type check:

ruff check src/ tests/
mypy src/wireshark_mcp/

Docker:

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

CLI options:

wireshark-mcp --version
wireshark-mcp --transport sse --port 8080 --log-level INFO

See CONTRIBUTING.md for the full development setup guide.

---

_{MIT License · Report a Bug}