┌───────────────────────┐
│     AI Assistant      │
│   Claude Desktop      │
└───────────┬───────────┘
            │
            │ MCP / JSON-RPC
            ▼
┌───────────────────────┐
│  Wireshark MCP Server │
│        Python         │
└───────────┬───────────┘
            │
            ▼
┌────────────────────────────────────────┐
│       Wireshark CLI Tools              │
│                                        │
│ tshark │ dumpcap │ capinfos │ mergecap │
└───────────┬────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────┐
│       Network / PCAP / PCAPNG       │
│                                     │
│ Live Traffic     Capture Files      │
└───────────┬─────────────────────────┘
            │
            ▼
┌───────────────────────┐
│   Structured Results  │
│   Packet / Protocol   │
│   Endpoint / Stream   │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│     AI Analysis       │
│ Explanation / Summary │
│ Troubleshooting       │
└───────────────────────┘

---

## 🎯 Project Goals

The project aims to provide an AI-accessible interface for:

- Live packet capture
- PCAP analysis
- Display-filter validation
- Protocol hierarchy analysis
- Endpoint analysis
- Conversation analysis
- TCP/UDP stream following
- Packet inspection
- Capture metadata extraction
- Packet export
- Capture file merging

---

## 🧰 Technologies

| Technology | Purpose |
|---|---|
| Python | MCP server implementation |
| Model Context Protocol | AI ↔ tool communication |
| Wireshark | Packet analysis |
| tshark | CLI packet analyzer |
| dumpcap | Packet capture |
| capinfos | Capture metadata |
| mergecap | PCAP merging |
| Claude Desktop | MCP client |

---

## ✨ Features

### Capture

- List network interfaces
- Start live captures
- Stop captures
- Monitor active captures
- Perform short quick captures

### PCAP Analysis

- Read PCAP/PCAPNG files
- Inspect individual packets
- Analyze protocol hierarchy
- Analyze conversations
- Analyze endpoints
- Follow network streams

### Filtering

- Validate Wireshark display filters
- Apply filters to packet analysis
- Export filtered packets

### File Operations

- List generated capture files
- Merge multiple capture files
- Retrieve capture metadata

---

## 🔧 MCP Tools

| Tool | Description |
|---|---|
| `list_interfaces` | List available network interfaces |
| `get_interface_statistics` | Retrieve interface traffic statistics |
| `start_live_capture` | Start a background packet capture |
| `get_capture_status` | Check capture status |
| `list_active_captures` | List running captures |
| `stop_live_capture` | Stop an active capture |
| `quick_capture` | Perform a short packet capture |
| `read_pcap_file` | Read and analyze PCAP files |
| `get_packet_details` | Retrieve detailed packet information |
| `get_protocol_hierarchy` | Analyze protocol distribution |
| `get_conversations` | Analyze network conversations |
| `get_endpoints` | Analyze network endpoints |
| `follow_stream` | Follow TCP/UDP/HTTP/TLS streams |
| `get_capture_summary` | Retrieve capture metadata |
| `export_filtered_packets` | Export filtered packets |
| `merge_capture_files` | Merge capture files |
| `list_capture_files` | List generated captures |
| `validate_display_filter` | Validate Wireshark display filters |

---

## 💻 Installation

git clone https://github.com/dhruvjaiswal-98/wireshark-mcp-server.git
cd wireshark-mcp-server

Wireshark must be installed on the host system.
Verify:
tshark --version
dumpcap --version
capinfos --version

pip install -r requirements.txt

🤖 Claude Desktop Configuration
Add the MCP server to your Claude Desktop configuration.
Example:
{
  "mcpServers": {
    "wireshark": {
      "command": "python",
      "args": [
        "/absolute/path/to/server.py"
      ]
    }
  }
}
Restart Claude Desktop after changing the configuration.

## 🔄 How It Works

1. The user sends a network-analysis request to the AI assistant.
2. The AI assistant determines which MCP tool is required.
3. The MCP client sends a structured request to the Wireshark MCP server.
4. The MCP server validates the requested operation.
5. The server executes the appropriate Wireshark CLI utility.
6. Wireshark processes the packet capture or live traffic.
7. The MCP server converts the result into structured output.
8. The AI assistant interprets the result and provides an explanation.

Once connected, you can ask:
Interface discovery
List my available network interfaces.

Packet capture
Capture traffic for 15 seconds and summarize the protocols observed.

DNS analysis
Analyze this PCAP and list all DNS queries.

HTTP analysis
Find HTTP traffic and summarize the hosts contacted.

TCP analysis
Show the top TCP conversations sorted by bytes.

Troubleshooting
Analyze this PCAP and identify unusual retransmissions or connection failures.

Security analysis
Analyze this capture for suspicious network behavior and explain your findings.

This project executes Wireshark command-line utilities on the local system.
Because packet capture can expose sensitive information:
- Only capture traffic on systems/networks you are authorized to monitor.
- Avoid uploading sensitive PCAP files to third-party services.
- Be careful when following streams containing credentials or personal data.
- Restrict access to generated capture files.
- Do not use packet capture capabilities against systems without authorization.
This project is intended for:
- Security labs
- Network troubleshooting
- CTF environments
- Authorized security testing
- Educational purposes