Wireshark MCP Server

# 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