mixelpixx/Wireshark-MCP

Wireshark MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with professional-grade network analysis capabilities. Combines Wireshark packet analysis with nmap scanning, threat intelligence, and modern MCP features for enhanced network troubleshooting and security analysis.

Features

Core Wireshark Capabilities

• Live Packet Capture: Real-time network traffic capture from any interface
• PCAP File Analysis: Advanced analysis of capture files with filtering
• Protocol Statistics: Comprehensive protocol hierarchy and conversation stats
• Stream Following: Reconstruct TCP/UDP conversations from captures
• Data Export: Export packets to JSON, CSV formats

Network Scanning (Nmap Integration)

• Port Scanning: Multiple scan types (SYN, connect, UDP)
• Service Detection: Identify services and versions
• OS Fingerprinting: Operating system detection
• Vulnerability Scanning: NSE vulnerability detection scripts
• Quick & Comprehensive Scans: Flexible scan options

Security Features

• Threat Intelligence: URLhaus and AbuseIPDB integration
• Malicious IP Detection: Automatic threat checking
• Security Audit Workflows: Guided security analysis prompts
• Credential Scanning: Detect cleartext credentials
• Defense in Depth: Multiple layers of input validation

Modern MCP Features

• MCP Resources: Dynamic access to interfaces and captures
• MCP Prompts: Guided workflows for security audits and troubleshooting
• Structured JSON Output: LLM-optimized response formats
• Rate Limiting: Prevent abuse of scanning operations
• Async Operations: Non-blocking high-performance analysis

Installation

Quick Install (PyPI)

pip install wireshark-mcp-server

Development Install

# Clone repository
git clone https://github.com/yourusername/wireshark-mcp.git
cd wireshark-mcp

# Install in development mode
pip install -e .

# Or install from requirements
pip install -r requirements.txt

Requirements

System Requirements

• Python 3.8+ with pip
• Wireshark/TShark installed and in PATH
• Nmap (optional, for scanning features)
• Network capture permissions (see setup below)

Installation Commands

Ubuntu/Debian

sudo apt-get update
sudo apt-get install tshark nmap
sudo usermod -aG wireshark $USER

macOS

brew install wireshark nmap

Windows

1. Download and install Wireshark
2. Download and install Nmap
3. Run as Administrator for packet capture

Network Permissions

Linux (Recommended)

# Set capabilities on dumpcap (no root needed)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Or add user to wireshark group
sudo usermod -aG wireshark $USER
newgrp wireshark  # Apply group without logout

Configuration

Claude Desktop

Edit your Claude Desktop config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wireshark": {
      "command": "wireshark-mcp-server",
      "env": {
        "ABUSEIPDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Environment Variables

# Optional: AbuseIPDB API key for threat intelligence
export ABUSEIPDB_API_KEY="your_api_key_here"

# Optional: VirusTotal API key (future support)
export VIRUSTOTAL_API_KEY="your_api_key_here"

Available Tools

Network Interface & Capture (5 tools)

get_network_interfaces()

• Lists all available network interfaces

capture_live_packets(interface, count, capture_filter, timeout, format)

• Captures live packets with BPF filtering
• Supports JSON and text output formats

analyze_pcap_file(filepath, display_filter, max_packets)

• Analyzes PCAP files with Wireshark display filters

get_protocol_statistics(filepath)

• Generates protocol hierarchy and IP conversations

get_capture_file_info(filepath)

• Retrieves capture file metadata

Stream Analysis (3 tools)

follow_tcp_stream(filepath, stream_index, format)

• Reconstructs TCP conversations (ASCII, hex, raw)

follow_udp_stream(filepath, stream_index, format)

• Reconstructs UDP conversations

list_tcp_streams(filepath)

• Lists all TCP conversations in capture

Data Export (3 tools)

export_packets_json(filepath, display_filter, max_packets)

• Exports packets to structured JSON

export_packets_csv(filepath, fields, display_filter)

• Exports custom fields to CSV

convert_pcap_format(filepath, output_format)

• Converts between pcap/pcapng formats

Nmap Scanning (6 tools)

nmap_port_scan(target, ports, scan_type, format)

• Scans for open ports (connect, SYN, UDP)

nmap_service_detection(target, ports)

• Detects service versions

nmap_os_detection(target)

• Identifies operating system (requires root)

nmap_vulnerability_scan(target, ports)

• Runs NSE vulnerability scripts

nmap_quick_scan(target)

• Fast scan of top 100 ports

nmap_comprehensive_scan(target)

• Full scan with all features

Threat Intelligence (2 tools)

check_ip_threat_intel(ip_or_filepath, providers)

• Checks IPs against URLhaus, AbuseIPDB

scan_capture_for_threats(filepath, providers)

• Comprehensive threat scan of PCAP file

MCP Resources

wireshark://interfaces/

• Dynamic list of network interfaces

wireshark://captures/

• Available PCAP files in common directories

wireshark://system/info

• System capabilities and tool availability

network://help

• Comprehensive tool documentation

MCP Prompts

security_audit

• Guided security analysis workflow

network_troubleshooting

• Network diagnostics workflow

incident_response

• Security incident investigation workflow

Usage Examples

Basic Network Capture

User: "Capture 100 packets from eth0 with HTTP traffic"
AI: Uses capture_live_packets("eth0", 100, "tcp port 80")

Security Analysis Workflow

User: "Perform a security audit on suspicious.pcap"
AI:
1. Uses security_audit prompt
2. Analyzes file with get_protocol_statistics()
3. Extracts IPs and checks scan_capture_for_threats()
4. Follows suspicious TCP streams
5. Generates comprehensive report

Scan & Capture Workflow

User: "Scan 192.168.1.100 then capture its traffic"
AI:
1. nmap_quick_scan("192.168.1.100")
2. capture_live_packets("eth0", 500, "host 192.168.1.100")
3. analyze_pcap_file() with findings
4. follow_tcp_stream() for interesting connections

Threat Intelligence Check

User: "Check if this capture has any malicious IPs"
AI: scan_capture_for_threats("/path/to/capture.pcap", "urlhaus,abuseipdb")

Security

Input Validation

• IP/CIDR/hostname validation
• Port range validation
• BPF and display filter sanitization
• File path resolution and sandboxing

Command Injection Prevention

• shell=False enforced in ALL subprocess calls
• List-based command construction
• No user input directly in shell commands

Rate Limiting

• Max 10 nmap scans per hour
• Configurable scan history tracking

Privilege Management

• Detects when root/sudo required
• Never auto-escalates privileges
• Clear error messages for permission issues

Audit Logging

• All scans logged with timestamps
• Security-relevant operations tracked
• Validation failures recorded

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# With coverage
pytest --cov=wireshark_mcp --cov-report=html

# Linting
ruff check wireshark_mcp/
black --check wireshark_mcp/

# Type checking
mypy wireshark_mcp/

Project Structure

wireshark_mcp/
├── server.py                   # Main server orchestration
├── core/
│   ├── security.py             # Security validation
│   └── output_formatter.py     # Response formatting
├── interfaces/
│   ├── wireshark_interface.py  # TShark wrapper
│   ├── nmap_interface.py       # Nmap wrapper
│   └── threat_intel_interface.py # Threat APIs
├── tools/
│   ├── capture.py              # Capture tools
│   ├── analysis.py             # Analysis tools
│   ├── nmap_scan.py            # Scanning tools
│   ├── network_streams.py      # Stream tools
│   ├── export.py               # Export tools
│   └── threat_intel.py         # Threat tools
├── resources/                  # MCP Resources
└── prompts/                    # MCP Prompts

Troubleshooting

"TShark not found"

# Verify installation
tshark --version

# Add to PATH or use absolute path
export PATH=$PATH:/usr/bin

"Permission denied" for capture

# Linux - set capabilities
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Or use sudo (not recommended)
sudo wireshark-mcp-server

"Nmap not available"

# Install nmap
sudo apt-get install nmap  # Debian/Ubuntu
brew install nmap           # macOS

# Verify
nmap --version

Threat Intelligence Not Working

# Check API key
echo $ABUSEIPDB_API_KEY

# URLhaus requires no key (works by default)
# AbuseIPDB requires free API key from https://www.abuseipdb.com/

License

MIT License - see LICENSE file for details

Acknowledgments

• Built on the Model Context Protocol (MCP) by Anthropic
• Powered by Wireshark network analysis toolkit
• Integrated with Nmap security scanner
• Threat intelligence from URLhaus and AbuseIPDB

Support

• Issues: GitHub Issues
• Documentation: See network://help resource in MCP
• Security: Report vulnerabilities via GitHub Security Advisories

Roadmap

• GeoIP enrichment for IP addresses
• HTTP/TLS credential extraction
• Real-time WebSocket streaming
• VirusTotal integration
• AlienVault OTX integration
• Machine learning traffic classification
• Anomaly detection algorithms
• PCAP merging and splitting tools
• Statistics visualization export

Transform your network analysis with AI-powered Wireshark + Nmap integration