wireshark-mcp 0.4.0
A production-grade Model Context Protocol (MCP) server for Wireshark
Requires Python: >=3.10

# Wireshark MCP

Simple [MCP Server](https://modelcontextprotocol.io/introduction) to allow vibe packet analysis in Wireshark.

[English](README.md) | [中文](README_zh.md)

## Prerequisites

- [Python](https://www.python.org/downloads/) (**3.10 or higher**)
- [Wireshark](https://www.wireshark.org/) (ensure `tshark` is in your PATH)
- Supported MCP Client (pick one you like)
  - [Claude Code](https://www.anthropic.com/code)
  - [Claude](https://claude.ai/download)
  - [Cursor](https://cursor.com)
  - [VS Code](https://code.visualstudio.com/) with generic MCP client extension
  - [Other MCP Clients](https://modelcontextprotocol.io/clients#example-clients)

## Installation

Install the latest version of the Wireshark MCP package:

```sh
pip install wireshark-mcp
```

Or install directly from source:

```sh
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`):

```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:

```md
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:

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

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