README.md•8.38 kB
# 🦈 Wireshark MCP Server - Production Ready
> **Professional Wireshark MCP server with 18 comprehensive network analysis tools for Claude Desktop integration.**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://claude.ai/desktop)
[](#tools)
[](#test-results)
## 🚀 **Features**
- **18 Complete Network Analysis Tools** - Comprehensive packet analysis suite
- **Real-time JSON Streaming** - Live packet capture in multiple formats
- **Advanced PCAP Operations** - Split, merge, time-slice, and convert files
- **Security Analysis** - Threat detection and anomaly analysis
- **LLM-Powered Filter Generation** - Natural language to Wireshark filters
- **Enterprise-Ready** - Production-grade error handling and logging
---
## 📦 **Quick Setup**
### **Prerequisites**
```bash
# Linux (Ubuntu/Debian)
sudo apt-get install wireshark tshark tcpdump python3-pip
# macOS
brew install wireshark tcpdump python3
# Windows
choco install wireshark python3
```
### **Installation**
```bash
git clone https://github.com/priestlypython/wireshark-mcp.git
cd wireshark-mcp
pip install -r requirements.txt
# Configure permissions (Linux)
sudo usermod -a -G wireshark $USER
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap
newgrp wireshark
```
### **Claude Desktop Configuration**
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"wireshark-mcp": {
"command": "python",
"args": ["/path/to/wireshark-mcp/enhanced_server.py"],
"cwd": "/path/to/wireshark-mcp",
"env": {
"PYTHONPATH": "/path/to/wireshark-mcp",
"WIRESHARK_PATH": "/usr/bin",
"TSHARK_PATH": "/usr/bin/tshark",
"TCPDUMP_PATH": "/usr/sbin/tcpdump"
}
}
}
}
```
---
## 🛠️ **All 18 Tools**
### **Core Analysis Tools (8)**
| Tool | Purpose | Output |
|------|---------|--------|
| `wireshark_system_info` | System info & interfaces | JSON with capabilities |
| `wireshark_validate_setup` | Validate installation | Dependency status |
| `wireshark_generate_filter` | AI filter generation | Wireshark display filter |
| `wireshark_live_capture` | Live packet capture | Packet array |
| `wireshark_analyze_pcap` | PCAP analysis | Comprehensive stats |
| `wireshark_realtime_json_capture` | JSON streaming | Real-time packets |
| `wireshark_protocol_statistics` | Protocol analysis | Hierarchy & conversations |
| `wireshark_analyze_pcap_enhanced` | Advanced analysis | Security & performance |
### **Advanced Tools (10)**
| Tool | Purpose | Output |
|------|---------|--------|
| `wireshark_pcap_time_slice` | Extract time windows | Time-sliced PCAP |
| `wireshark_pcap_splitter` | Split PCAP files | Multiple split files |
| `wireshark_pcap_merger` | Merge PCAP files | Merged PCAP file |
| `wireshark_hex_to_pcap` | Convert hex to PCAP | PCAP file |
| `wireshark_http_analyzer` | HTTP traffic analysis | Transaction details |
| `wireshark_dns_analyzer` | DNS query analysis | Query patterns & anomalies |
| `wireshark_ssl_inspector` | SSL/TLS inspection | Certificate & cipher info |
| `wireshark_latency_profiler` | Performance analysis | Latency metrics |
| `wireshark_threat_detector` | Security analysis | Threat scores & indicators |
| `wireshark_remote_capture` | SSH remote capture | Remote packet data |
---
## 💡 **Usage Examples**
### **System Information**
```python
# Check system capabilities
wireshark_system_info(info_type="all")
# → Returns interfaces, capabilities, server status
```
### **Live Packet Capture**
```python
# Capture HTTP traffic for 30 seconds
wireshark_live_capture(
interface="eth0",
duration=30,
filter="tcp port 80",
max_packets=1000
)
# → Returns captured packets with analysis
```
### **PCAP Analysis**
```python
# Comprehensive PCAP analysis
wireshark_analyze_pcap(
filepath="/path/to/capture.pcap",
analysis_type="comprehensive"
)
# → File info, protocols, security analysis
```
### **Filter Generation**
```python
# Generate filter from natural language
wireshark_generate_filter(
description="Show all HTTP traffic from 192.168.1.0/24",
complexity="intermediate"
)
# → Returns optimized Wireshark filter
```
### **PCAP Operations**
```python
# Split large PCAP by time
wireshark_pcap_time_slice(
input_file="/path/to/large.pcap",
start_time="2025-01-01T10:00:00",
end_time="2025-01-01T11:00:00"
)
# → Creates time-sliced PCAP file
# Merge multiple PCAPs
wireshark_pcap_merger(
input_files=["file1.pcap", "file2.pcap"],
output_file="merged.pcap",
sort_chronologically=true
)
# → Creates chronologically sorted merged file
```
### **Security Analysis**
```python
# Threat detection
wireshark_threat_detector(
input_file="/path/to/suspicious.pcap",
detection_mode="comprehensive",
sensitivity="high"
)
# → Threat scores, anomalies, behavioral analysis
# DNS tunneling detection
wireshark_dns_analyzer(
input_file="/path/to/capture.pcap",
analysis_type="comprehensive",
detect_tunneling=true
)
# → DNS patterns, suspicious domains, entropy analysis
```
---
## 🔧 **Expected Outputs**
### **Structured JSON Results**
All tools return well-structured JSON with:
- **Status indicators** (✅ Success, ❌ Error)
- **Rich metadata** (file sizes, timestamps, statistics)
- **Analysis results** (protocols, conversations, threats)
- **Recommendations** (filter suggestions, security insights)
### **File Operations**
PCAP manipulation tools create properly formatted files:
- Time-sliced captures with precise timestamps
- Split files with organized naming conventions
- Merged files with chronological packet ordering
- Converted files maintaining packet integrity
### **Security Intelligence**
Advanced analysis provides:
- **Threat scores** (0-100 risk assessment)
- **Anomaly detection** (statistical analysis)
- **Pattern recognition** (attack signatures)
- **Behavioral analysis** (network health indicators)
---
## 🚨 **Troubleshooting**
### **Permission Issues (Common)**
```bash
# Linux: Set capabilities
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap
sudo usermod -a -G wireshark $USER
# macOS: Run Wireshark as admin once
sudo /Applications/Wireshark.app/Contents/MacOS/Wireshark
# Windows: Run as Administrator
```
### **Tool Not Found**
- Ensure Wireshark is installed and in PATH
- Check `wireshark_validate_setup` tool for missing dependencies
- Verify configuration paths in Claude Desktop config
### **No Packets Captured**
- Check interface permissions with `wireshark_system_info`
- Verify network traffic exists on selected interface
- Try different interface (eth0, wlan0, any)
---
## ✅ **Test Results**
**Latest Test Date**: 2025-08-20
**Success Rate**: 94.4% (17/18 tools fully operational)
| Category | Tools | Status |
|----------|-------|--------|
| Core System Tools | 3/3 | ✅ 100% |
| Capture Tools | 2/2 | ✅ 100% |
| Analysis Tools | 4/4 | ✅ 100% |
| PCAP Manipulation | 4/4 | ✅ 100% |
| Protocol Analyzers | 4/4 | ✅ 100% |
| Remote Capture | 0/1 | ⚠️ Requires SSH |
See [WIRESHARK_MCP_TEST_REPORT.md](WIRESHARK_MCP_TEST_REPORT.md) for detailed test results.
---
## 📊 **Performance**
- **Processing Rate**: 10,000+ packets/second
- **File Support**: Multi-GB PCAP files with streaming
- **Memory Efficient**: Chunked processing for large files
- **Real-time**: Sub-second response times
- **Concurrent**: Multiple analysis operations supported
- **Average Response**: ~300ms per operation
---
## 🛡️ **Security**
- **Secure Permissions**: Linux capabilities instead of root
- **Process Isolation**: Sandboxed subprocess execution
- **Automatic Cleanup**: Temporary files removed after use
- **Audit Logging**: Comprehensive operation logging
- **Error Handling**: Graceful failure with informative messages
---
## 📄 **License**
MIT License - see [LICENSE](LICENSE) for details.
---
**🦈 Professional network analysis powered by AI. Built for enterprise, designed for developers.**