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

Install Wireshark with WinPcap/Npcap during installation
Run as Administrator or ensure user has network capture permissions

Linux

# 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

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

Installation

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

Configuration

Claude Desktop Integration

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

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"
      }
    }
  }
}

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

"TShark not found" error
- Ensure Wireshark is installed and tshark is in your PATH
- On Windows, check C:\Program Files\Wireshark\tshark.exe
Permission denied for packet capture
- Follow the network permissions setup instructions above
- On Linux/macOS, you may need to use sudo for live captures
"FastMCP not installed" error
- Install required dependencies: pip install -r requirements.txt
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:

export MCP_LOG_LEVEL=DEBUG
python wireshark-mcp-server.py

Development

Testing the Server

# 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

Fork the repository
Create a feature branch
Add tests for new functionality
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:

Check the troubleshooting section above
Verify Wireshark installation and permissions
Check the project logs for detailed error messages
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

Wireshark MCP Server

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

Install Wireshark with WinPcap/Npcap during installation
Run as Administrator or ensure user has network capture permissions

Linux

# 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

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

Installation

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

Configuration

Claude Desktop Integration

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

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"
      }
    }
  }
}

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

"TShark not found" error
- Ensure Wireshark is installed and tshark is in your PATH
- On Windows, check C:\Program Files\Wireshark\tshark.exe
Permission denied for packet capture
- Follow the network permissions setup instructions above
- On Linux/macOS, you may need to use sudo for live captures
"FastMCP not installed" error
- Install required dependencies: pip install -r requirements.txt
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:

export MCP_LOG_LEVEL=DEBUG
python wireshark-mcp-server.py

Development

Testing the Server

# 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

Fork the repository
Create a feature branch
Add tests for new functionality
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:

Check the troubleshooting section above
Verify Wireshark installation and permissions
Check the project logs for detailed error messages
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