# TShark MCP

MCP service for analyzing network traffic with tshark.

## Installation

```bash
pip install -e .
```

## Requirements

- Python 3.10+
- tshark (part of Wireshark)

## Configuration

### TShark Path

By default, the service will search for tshark in the following order:

1. `TSHARK_PATH` environment variable
2. macOS default: `/Applications/Wireshark.app/Contents/MacOS/tshark`
3. System PATH

You can set the tshark path via environment variable:

```bash
export TSHARK_PATH=/path/to/tshark
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "tshark": {
      "command": "/path/to/python",
      "args": ["-m", "tshark_mcp.server"],
      "env": {
        "TSHARK_PATH": "/Applications/Wireshark.app/Contents/MacOS/tshark"
      }
    }
  }
}
```

## Usage

Start the MCP server:

```bash
tshark-mcp
```

Or run directly:

```bash
python -m tshark_mcp.server
```

## Tools

### analyze_pcap_file

Analyze a pcap/pcapng file and extract all TCP streams with their application layer data.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `filter` (optional): BPF filter expression

**Returns:** All TCP streams with protocol identification and payload data.

### list_tcp_streams

List all TCP streams in a pcap file with basic information.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file

**Returns:** Stream list with addresses, ports, packet counts, and protocol.

### extract_stream_data

Extract payload data from a specific TCP stream.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `stream_index` (required): TCP stream index (0-based)
- `direction` (optional): "client", "server", or "both" (default: "both")

**Returns:** Payload data for the specified direction(s).

### analyze_pcap_data

Analyze base64-encoded pcap data.

**Parameters:**
- `data` (required): Base64-encoded pcap/pcapng data
- `filter` (optional): BPF filter expression

**Returns:** All TCP streams with protocol identification and payload data.

### list_tcp_packets

List all TCP packets in a pcap file with detailed information.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `stream_index` (optional): TCP stream index to filter packets
- `filter` (optional): BPF filter expression

**Returns:** Packet list with frame number, time, addresses, ports, protocol, and length.

### list_udp_streams

List all UDP streams in a pcap file with basic information.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `filter` (optional): BPF filter expression

**Returns:** Stream list with addresses, ports, packet counts, and protocol.

### list_udp_packets

List all UDP packets in a pcap file with detailed information.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `filter` (optional): BPF filter expression

**Returns:** Packet list with frame number, time, addresses, ports, protocol, and length.

### list_icmp_packets

List all ICMP packets in a pcap file with detailed information. Useful for analyzing ICMP tunnels and ping traffic.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `filter` (optional): BPF filter expression

**Returns:** Packet list with frame number, time, addresses, ICMP type/code, length, and payload (hex and ASCII).

**ICMP Types:**
- Type 0: Echo Reply
- Type 8: Echo Request
- Type 3: Destination Unreachable
- Type 11: Time Exceeded

### list_dns_queries

List all DNS queries in a pcap file with domain names and response IPs. Requests and responses are automatically correlated by transaction ID.

**Parameters:**
- `file_path` (required): Path to the pcap/pcapng file
- `filter` (optional): BPF filter expression

**Returns:** Query list with domain name, query type, transaction ID, request/response frames, and response IPs.