wireshark-mcp 0.4.0

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

Wireshark MCP

Simple MCP Server to allow vibe packet analysis in Wireshark.

English | 中文

Prerequisites

• Python (3.10 or higher)
• Wireshark (ensure tshark is in your PATH)
• Supported MCP Client (pick one you like)
  • Claude Code
  • Claude
  • Cursor
  • VS Code with generic MCP client extension
  • Other MCP Clients

Installation

Install the latest version of the Wireshark MCP package:

pip install wireshark-mcp

Or install directly from source:

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

Configuration

Add the server to your MCP client configuration (e.g., claude_desktop_config.json):

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

Note: You can also run it directly with python -m wireshark_mcp if installed in your environment.

Prompt Engineering

LLMs are good at general analysis but can struggle with the specifics of packet dissection. Below is a minimal example prompt strategy:

Your task is to analyze a pcap file using Wireshark MCP tools.
- Start by getting a packet list summary to understand the traffic flow (`wireshark_get_packet_list`).
- If you see interesting packets, get full details for that specific frame (`wireshark_get_packet_details`).
- For TCP/HTTP flows, use `wireshark_follow_stream` to see the full conversation.
- Use `wireshark_extract_http_requests` or `wireshark_extract_dns_queries` for quick high-level overviews.
- NEVER try to guess packet contents; always verify with the tools.
- Create a report.md with your findings.

Available Tools

Packet Analysis (extract.py)

• wireshark_get_packet_list(pcap_file, limit=20, offset=0, display_filter="", custom_columns=""): Get summary list of packets. Supports custom columns (e.g., "ip.src,http.host") to replace default view.
• wireshark_get_packet_details(pcap_file, frame_number, layers=""): Get full JSON details for a single packet. Supports layer filtering (e.g., "ip,tcp,http") to significantly reduce token usage.
• wireshark_get_packet_bytes(pcap_file, frame_number): [New] Get raw Hex/ASCII dump (Packet Bytes view).
• wireshark_get_packet_context(pcap_file, frame_number, count=5): [New] View packets surrounding a specific frame (before and after) to understand context.
• wireshark_follow_stream(...): Reassemble and view complete stream content with pagination and search.
• wireshark_search_packets(pcap_file, match_pattern, search_type="string", limit=50, scope="bytes"): [Enhanced] Find packets.
  • scope="bytes": Search in raw payload (Hex/String).
  • scope="details": Search in decoded text/fields (Regex supported).
• wireshark_read_packets(...): [DEPRECATED] Use get_packet_details instead.

Data Extraction (extract.py)

• wireshark_extract_fields(pcap_file, fields, display_filter="", limit=100, offset=0): Extract specific fields as tabular data.
• wireshark_extract_http_requests(pcap_file, limit=100): Convenience tool for HTTP method, URI, host.
• wireshark_extract_dns_queries(pcap_file, limit=100): Convenience tool for DNS queries.
• wireshark_list_ips(pcap_file, type="both"): List all unique IP addresses (src, dst, or both).
• wireshark_export_objects(pcap_file, protocol, dest_dir): Extract embedded files (http, smb, etc.) from traffic.
• wireshark_verify_ssl_decryption(pcap_file, keylog_file): Verify TLS decryption using a keylog file.

Statistics (stats.py)

• wireshark_stats_protocol_hierarchy(pcap_file): Get Protocol Hierarchy Statistics (PHS).
• wireshark_stats_endpoints(pcap_file, type="ip"): List all endpoints and their traffic stats.
• wireshark_stats_conversations(pcap_file, type="ip"): Show communication pairs and their stats.
• wireshark_stats_io_graph(pcap_file, interval=1): Get traffic volume over time (I/O Graph).
• wireshark_stats_expert_info(pcap_file): Get Expert Information (anomalies, warnings).
• wireshark_stats_service_response_time(pcap_file, protocol="http"): Service Response Time (SRT) statistics.

File Operations (files.py & capture.py)

• wireshark_get_file_info(pcap_file): Get detailed metadata about a capture file (capinfos).
• wireshark_merge_pcaps(output_file, input_files): Merge multiple capture files into one.
• wireshark_list_interfaces(): List available network interfaces for capture.
• wireshark_capture(interface, output_file, duration_seconds=10, packet_count=0, capture_filter="", ring_buffer=""): Capture live network traffic.
• wireshark_filter_save(input_file, output_file, display_filter): Filter packets from a pcap and save to a new file.

Security (security.py)

• wireshark_check_threats(pcap_file): Check captured IPs against URLhaus threat intelligence.
• wireshark_extract_credentials(pcap_file): Scan for plaintext credentials (HTTP Auth, FTP, Telnet).

Decoding (decode.py)

• wireshark_decode_payload(data, encoding="auto"): Decode common encodings (Base64, Hex, URL, Gzip, Deflate, Rot13, etc.) with smart auto-detection.

Visualization (visualize.py)

• wireshark_plot_traffic(pcap_file, interval=1): Generate ASCII bar chart of traffic volume over time.
• wireshark_plot_protocols(pcap_file): Generate ASCII tree view of protocol hierarchy.

Development

To test the MCP server itself:

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

This will open a web interface where you can interact with the tools directly.