# Wireshark MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with direct access to Wireshark network analysis capabilities. This tool enables AI-powered network troubleshooting, packet analysis, and network monitoring through a secure, standardized interface.

## Features

- **Live Packet Capture**: Capture network traffic in real-time from any network interface
- **PCAP File Analysis**: Analyze existing packet capture files with advanced filtering
- **Protocol Statistics**: Generate comprehensive protocol hierarchy and conversation statistics
- **Network Interface Management**: List and interact with available network interfaces
- **Security Controls**: Comprehensive input validation and privilege management
- **Async Operations**: Non-blocking operations for high-performance analysis

## Requirements

### System Requirements
- **Python 3.9+** with pip package manager
- **Wireshark/TShark** installed and accessible from command line
- **Network capture permissions** (see setup instructions below)
- **Windows/Linux/macOS** compatibility

### Network Permissions Setup

#### Windows
1. Install Wireshark with WinPcap/Npcap during installation
2. Run as Administrator or ensure user has network capture permissions

#### Linux
```bash
# Add user to wireshark group
sudo usermod -aG wireshark $USER

# Or set capabilities on dumpcap (preferred)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Logout and login again for group changes to take effect
```

#### macOS
```bash
# Ensure user has admin privileges or use sudo for captures
# Wireshark installer typically handles permissions
```

## Installation

1. **Clone or download the project files**
2. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```
3. **Verify Wireshark installation:**
   ```bash
   tshark --version
   ```

## Configuration

### Claude Desktop Integration

1. **Locate your Claude Desktop config file:**
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Add the Wireshark MCP server configuration:**
   ```json
   {
     "mcpServers": {
       "wireshark": {
         "command": "python",
         "args": ["/absolute/path/to/wireshark-mcp-server.py"],
         "env": {
           "PYTHONPATH": "/absolute/path/to/project/directory",
           "MCP_LOG_LEVEL": "INFO"
         }
       }
     }
   }
   ```

3. **Restart Claude Desktop** to load the new server

### VS Code/Cursor Integration

For VS Code or Cursor, configure the MCP server in your IDE's MCP settings, pointing to the `wireshark-mcp-server.py` file.

## Available Tools

### `get_network_interfaces()`
Lists all available network interfaces for packet capture.

**Usage:**
```
Please list the available network interfaces
```

### `capture_live_packets(interface, count, capture_filter, timeout)`
Captures live network packets from a specified interface.

**Parameters:**
- `interface`: Network interface name (e.g., "eth0", "Wi-Fi") or number (e.g., "1")
- `count`: Number of packets to capture (default: 50, max: 1000)
- `capture_filter`: BPF capture filter expression (optional)
- `timeout`: Capture timeout in seconds (default: 30, max: 60)

**Usage:**
```
Capture 100 packets from interface eth0 with filter "tcp port 80"
```

### `analyze_pcap_file(filepath, display_filter, max_packets)`
Analyzes existing PCAP/PCAPNG files with optional filtering.

**Parameters:**
- `filepath`: Path to the PCAP/PCAPNG file
- `display_filter`: Wireshark display filter expression (optional)
- `max_packets`: Maximum number of packets to analyze (default: 100, max: 1000)

**Usage:**
```
Analyze the file /path/to/capture.pcap and show only HTTP requests
```

### `get_protocol_statistics(filepath)`
Generates protocol hierarchy and IP conversation statistics from a capture file.

**Parameters:**
- `filepath`: Path to the PCAP/PCAPNG file

**Usage:**
```
Generate protocol statistics for /path/to/capture.pcap
```

### `get_capture_file_info(filepath)`
Retrieves detailed information about a capture file (size, duration, packet count, etc.).

**Parameters:**
- `filepath`: Path to the PCAP/PCAPNG file

**Usage:**
```
Get information about the capture file /path/to/capture.pcap
```

## Filter Examples

### Capture Filters (BPF Syntax)
- `"tcp port 80"` - HTTP traffic
- `"host 192.168.1.1"` - Traffic to/from specific host
- `"net 10.0.0.0/8"` - Traffic on specific network
- `"tcp and port 443"` - HTTPS traffic
- `"icmp"` - ICMP/ping traffic

### Display Filters (Wireshark Syntax)
- `"http.request"` - HTTP requests only
- `"tcp.flags.syn == 1"` - TCP SYN packets
- `"dns.flags.response == 1"` - DNS responses
- `"ip.addr == 192.168.1.1"` - Traffic to/from specific IP
- `"tcp.analysis.retransmission"` - TCP retransmissions

## Security Features

- **Input Validation**: All user inputs are validated against security patterns
- **File Path Sanitization**: File paths are resolved and validated for safety
- **Resource Limits**: Capture duration, packet counts, and file sizes are limited
- **Interface Validation**: Only valid network interface names are accepted
- **Filter Validation**: Capture and display filters are checked for dangerous patterns

## Usage Examples

### Basic Network Troubleshooting
```
AI Assistant: "I need to troubleshoot network connectivity issues"
User: "Capture 200 packets from the main network interface and look for any issues"
```

### HTTP Traffic Analysis
```
AI Assistant: "Let me analyze your web traffic"
User: "Capture traffic on port 80 and 443 for 60 seconds and show me the top websites accessed"
```

### Security Investigation
```
AI Assistant: "Analyzing suspicious network activity"
User: "Examine this PCAP file for any unusual connections or potential security threats"
```

### Performance Analysis
```
AI Assistant: "Investigating network performance issues"
User: "Generate protocol statistics from this capture file to identify bandwidth usage"
```

## Troubleshooting

### Common Issues

1. **"TShark not found" error**
   - Ensure Wireshark is installed and `tshark` is in your PATH
   - On Windows, check `C:\Program Files\Wireshark\tshark.exe`

2. **Permission denied for packet capture**
   - Follow the network permissions setup instructions above
   - On Linux/macOS, you may need to use `sudo` for live captures

3. **"FastMCP not installed" error**
   - Install required dependencies: `pip install -r requirements.txt`

4. **Interface not found**
   - Use `get_network_interfaces()` to see available interfaces
   - Interface names vary by operating system

### Debug Mode

Enable debug logging by setting the environment variable:
```bash
export MCP_LOG_LEVEL=DEBUG
python wireshark-mcp-server.py
```

## Development

### Testing the Server
```bash
# Install development dependencies
pip install -r requirements.txt

# Test the server directly
python wireshark-mcp-server.py

# Run with debug logging
MCP_LOG_LEVEL=DEBUG python wireshark-mcp-server.py
```

### Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## License

This project is provided as-is for educational and professional use. Please ensure compliance with your organization's security and network monitoring policies.

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Verify Wireshark installation and permissions
3. Check the project logs for detailed error messages
4. Ensure all requirements are properly installed

## Acknowledgments

- Built on the Model Context Protocol (MCP) by Anthropic
- Utilizes the Wireshark network analysis toolkit
- Designed for secure, AI-powered network analysis