Wireshark MCP

# Linux Installation & Troubleshooting Guide This guide provides detailed instructions for installing and using Wireshark MCP on Linux systems, including handling common issues. ## Prerequisites Before you begin, ensure you have the following: 1. **Python 3.8+** installed on your system - Most Linux distributions come with Python pre-installed - If not, install using your distribution's package manager: ```bash # Ubuntu/Debian sudo apt-get update sudo apt-get install python3 python3-pip python3-venv # Fedora sudo dnf install python3 python3-pip python3-virtualenv # Arch Linux sudo pacman -S python python-pip ``` 2. **Git** installed on your system (for cloning the repository) ```bash # Ubuntu/Debian sudo apt-get install git # Fedora sudo dnf install git # Arch Linux sudo pacman -S git ``` 3. **Wireshark/TShark** installed on your system ```bash # Ubuntu/Debian sudo apt-get install wireshark tshark # Fedora sudo dnf install wireshark # Arch Linux sudo pacman -S wireshark-qt ``` After installation, you may need to add your user to the `wireshark` group to capture packets without root privileges: ```bash sudo usermod -a -G wireshark $USER # Log out and log back in for changes to take effect ``` ## Installation Methods ### Method 1: Standard Installation (via pip) ```bash pip3 install wireshark-mcp ``` ### Method 2: From Source (Recommended for Development) ```bash # Clone the repository git clone https://github.com/sarthaksiddha/Wireshark-mcp.git cd Wireshark-mcp # Create a virtual environment (recommended) python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt ``` ## Alternate Installation Method (If You Encounter Issues) If you encounter module import errors with the standard installation methods, you can use this approach: 1. Clone the repository: ```bash git clone https://github.com/sarthaksiddha/Wireshark-mcp.git cd Wireshark-mcp ``` 2. Create a virtual environment: ```bash python3 -m venv venv source venv/bin/activate ``` 3. Install dependencies directly (without installing the package in development mode): ```bash pip install pyshark scapy pydantic rich requests Jinja2 pip install -r web_interface/requirements.txt ``` 4. Set PYTHONPATH to include the repository directory: ```bash export PYTHONPATH=$PYTHONPATH:$(pwd) ``` This approach avoids issues with the package structure while still allowing you to use all the functionality. ## Using Wireshark MCP with Claude ### Simple Analysis Script For the most reliable method to analyze a PCAP file, especially if you encounter issues with other methods, use the `simple_pcap_analysis.py` script included in the `scripts` directory: ```bash cd scripts python simple_pcap_analysis.py /path/to/your/capture.pcap ``` This will: 1. Extract basic information from your PCAP file using TShark directly 2. Format it for Claude 3. Save the output to a markdown file that you can copy and paste into Claude ### Protocol-Specific Analysis To focus on a specific protocol: ```bash cd scripts python analyze_pcap.py /path/to/your/capture.pcap HTTP ``` Replace HTTP with the protocol you want to analyze (HTTP, DNS, TLS, SMTP, etc.) ## Web Interface To use the web interface: 1. Ensure you're in the repository directory and the virtual environment is activated: ```bash cd Wireshark-mcp source venv/bin/activate export PYTHONPATH=$PYTHONPATH:$(pwd) # If needed ``` 2. Start the web interface: ```bash cd web_interface python app.py ``` 3. Open a web browser and navigate to http://localhost:5000 ## Troubleshooting Linux-Specific Issues ### TShark Not Found or Not Working If you get a "TShark not found" error: 1. Verify TShark is installed by running: ```bash which tshark ``` 2. If not found but Wireshark is installed, install TShark separately: ```bash sudo apt-get install tshark # Ubuntu/Debian sudo dnf install wireshark-cli # Fedora sudo pacman -S tshark # Arch Linux ``` 3. If installed but not in PATH, specify the path explicitly: ```python # In your Python code mcp = WiresharkMCP("capture.pcap", tshark_path="/usr/bin/tshark") ``` ### Permission Issues for Packet Capture On Linux, capturing packets requires special permissions: 1. Make sure you're in the `wireshark` group: ```bash sudo usermod -a -G wireshark $USER # Log out and log back in for changes to take effect ``` 2. For analyzing existing PCAP files, ensure you have read permissions: ```bash chmod +r /path/to/your/capture.pcap ``` 3. If you encounter "permission denied" errors, try: ```bash sudo python scripts/simple_pcap_analysis.py /path/to/your/capture.pcap ``` ### Module Import Errors If you see errors like `No module named 'wireshark_mcp.protocols'`: 1. Make sure you're using the correct installation method (see "Alternate Installation Method" above) 2. Verify PYTHONPATH includes the Wireshark-mcp directory 3. Make sure all dependencies are installed ### Package Structure Issues If you encounter errors related to package installation (like multiple top-level packages): 1. Use the "Alternate Installation Method" above 2. Try the simple analysis script which doesn't rely on the package structure ### Distribution-Specific Issues #### Ubuntu/Debian - If you get `ImportError: libwiretap.so.X: cannot open shared object file`, try: ```bash sudo apt-get install libwireshark-dev ``` #### Fedora - If you get library errors, ensure Wireshark development packages are installed: ```bash sudo dnf install wireshark-devel ``` #### Arch Linux - If you get library errors, ensure all Wireshark components are installed: ```bash sudo pacman -S wireshark-cli wireshark-qt ``` ## Getting More Help If you encounter persistent issues: 1. Check the error message carefully for clues 2. Look at the [GitHub issues](https://github.com/sarthaksiddha/Wireshark-mcp/issues) to see if others have had similar problems 3. Create a new issue with detailed information about your environment and the error messages