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

macOS

Installation

1. Clone or download the project files
2. Install Python dependencies:
   pip install -r requirements.txt
3. Verify Wireshark installation:
   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:
   { "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:

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:

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:

get_protocol_statistics(filepath)

Generates protocol hierarchy and IP conversation statistics from a capture file.

Parameters:

• filepath: Path to the PCAP/PCAPNG file

Usage:

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:

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

HTTP Traffic Analysis

Security Investigation

Performance Analysis

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:

Development

Testing the Server

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