mcp-wireshark

An MCP server that integrates Wireshark/tshark with AI tools and IDEs. Capture live traffic, parse .pcap files, apply display filters, follow streams, and export JSON.

Comment

MCP Wireshark

Note: This is an unofficial, community-maintained MCP server and is not affiliated with or endorsed by Wireshark, Anthropic, or the official Model Context Protocol project.

An MCP (Model Context Protocol) server that integrates Wireshark/tshark with AI tools and IDEs. Capture live network traffic, parse .pcap files, apply display filters, follow TCP streams, and export to JSONβ€”all accessible through Claude Desktop, VS Code, or the command-line interface.

PyPI version License: MIT Python 3.10+ CI Code style: black Ruff MCP

οΏ½ New to this project? Start here: Getting Started Guide - Complete setup, publishing, and contribution guide!

πŸ“š Quick Start | πŸ“– API Docs | 🀝 Contributing | πŸš€ Publishing | πŸ’» Dev Setup

Features

  • πŸ” List Network Interfaces: Discover all available network interfaces for packet capture
  • πŸ“‘ Live Capture: Capture real-time network traffic from any interface
  • πŸ“‚ Read PCAP Files: Analyze existing .pcap and .pcapng files
  • πŸ”Ž Display Filters: Apply Wireshark's powerful display filters
  • πŸ“Š Protocol Statistics: Generate detailed protocol statistics
  • πŸ”— Follow TCP Streams: Extract and analyze TCP stream payloads
  • πŸ’Ύ Export to JSON: Export packet data in JSON format for further analysis

Prerequisites

  • Python 3.10 or higher
  • Wireshark/tshark installed on your system

Installing Wireshark/tshark

macOS (using Homebrew):

brew install wireshark

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install tshark

Windows: Download and install from Wireshark Downloads

Note: On Linux, you may need to add your user to the wireshark group to capture packets without root:

sudo usermod -aG wireshark $USER
sudo chmod +x /usr/bin/dumpcap

Installation

Install from PyPI:

pip install mcp-wireshark

Or install from source:

git clone https://github.com/khuynh22/mcp-wireshark.git
cd mcp-wireshark
pip install -e .

Usage

As an MCP Server

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "wireshark": {
      "command": "mcp-wireshark",
      "args": [],
      "env": {}
    }
  }
}

VS Code

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "wireshark": {
      "command": "mcp-wireshark",
      "args": [],
      "env": {}
    }
  }
}

Command Line

Run the MCP server:

mcp-wireshark

The server will communicate using stdio (standard input/output) following the MCP protocol.

Available Tools

1. list_interfaces

List all available network interfaces for packet capture.

Example:

Use the list_interfaces tool to see available network interfaces

2. live_capture

Capture live network traffic from a specified interface.

Parameters:

  • interface (required): Network interface name (e.g., "eth0", "Wi-Fi")
  • duration (optional): Capture duration in seconds (default: 10)
  • packet_count (optional): Maximum number of packets to capture
  • display_filter (optional): Wireshark display filter to apply

Example:

Capture packets from eth0 for 30 seconds with filter "tcp.port == 80"

3. read_pcap

Read and analyze packets from a .pcap or .pcapng file.

Parameters:

  • file_path (required): Path to the .pcap or .pcapng file
  • packet_count (optional): Maximum number of packets to read (default: 100)
  • display_filter (optional): Wireshark display filter to apply

Example:

Read the first 50 packets from capture.pcap

4. display_filter

Apply a Wireshark display filter to a pcap file.

Parameters:

  • file_path (required): Path to the .pcap or .pcapng file
  • filter (required): Wireshark display filter expression
  • packet_count (optional): Maximum number of packets to return (default: 100)

Example:

Filter packets from capture.pcap where tcp.port == 443

5. stats_by_proto

Generate protocol statistics from a pcap file.

Parameters:

  • file_path (required): Path to the .pcap or .pcapng file

Example:

Generate protocol statistics for capture.pcap

6. follow_tcp

Follow a TCP stream and extract payload data.

Parameters:

  • file_path (required): Path to the .pcap or .pcapng file
  • stream_id (optional): TCP stream ID to follow (default: 0)

Example:

Follow TCP stream 0 from capture.pcap

7. export_json

Export packets from a pcap file to JSON format.

Parameters:

  • file_path (required): Path to the .pcap or .pcapng file
  • output_path (required): Path to save the JSON output
  • packet_count (optional): Maximum number of packets to export (default: 1000)
  • display_filter (optional): Wireshark display filter to apply

Example:

Export first 500 HTTP packets from capture.pcap to output.json

Common Display Filters

Here are some useful Wireshark display filters:

  • tcp.port == 80 - HTTP traffic
  • tcp.port == 443 - HTTPS traffic
  • http - All HTTP packets
  • dns - DNS queries and responses
  • ip.addr == 192.168.1.1 - Traffic to/from specific IP
  • tcp.flags.syn == 1 - TCP SYN packets
  • http.request.method == "GET" - HTTP GET requests
  • tcp.stream eq 0 - Packets from TCP stream 0

For more filters, see the Wireshark Display Filter Reference.

Cross-Platform Support

mcp-wireshark is designed to work across multiple platforms:

  • macOS: Full support with Homebrew-installed Wireshark
  • Linux: Full support with apt/yum-installed tshark
  • Windows: Full support with official Wireshark installer

The tool uses dumpcap when available (recommended for non-root captures) and falls back to tshark when needed.

Development

Want to contribute? See our comprehensive guides:

Quick Start for Developers

# Clone and setup
git clone https://github.com/khuynh22/mcp-wireshark.git
cd mcp-wireshark
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run quality checks
pytest                    # Run tests
black src tests          # Format code
ruff check src tests     # Lint
mypy src                 # Type check

Examples

See the examples directory for sample scripts and usage patterns.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Support

For issues, questions, or contributions, please visit the GitHub repository.

Built With

Share this project:

Updates