README.md•6.99 kB
# Wireshark MCP (Model Context Protocol)
[](LICENSE)
[](https://www.python.org/downloads/)
A Model Context Protocol (MCP) server for integrating Wireshark network analysis capabilities with AI systems like Claude. This implementation provides direct integration with Claude without requiring manual copy/paste of prompts.
## What is Wireshark MCP?
Wireshark MCP provides a standardized way for AI assistants to access and analyze network packet data through Wireshark. It bridges the gap between low-level network data and high-level AI understanding by implementing the Model Context Protocol.
<p align="center">
<img src="https://raw.githubusercontent.com/sarthaksiddha/Wireshark-mcp/main/docs/images/wireshark-mcp-flow.png" alt="Wireshark MCP Flow" width="600"/>
</p>
The server provides tools for:
1. Capturing live network traffic
2. Analyzing existing pcap files
3. Extracting protocol-specific information
4. Summarizing network flows
## Quick Start
### Installation
```bash
# Clone the repository
git clone https://github.com/sarthaksiddha/Wireshark-mcp.git
cd Wireshark-mcp
# Install dependencies
pip install -e .
```
### Running the MCP Server
```bash
# Run with stdio transport (for Claude Desktop)
python mcp_server.py --stdio
# Run with SSE transport (for other MCP clients)
python mcp_server.py --host 127.0.0.1 --port 5000
```
### Configuring Claude Desktop
To configure Claude Desktop to use the Wireshark MCP server:
1. Open Claude Desktop
2. Go to Settings > Developer > Edit Config
3. Add the following configuration:
```json
{
"mcpServers": {
"wireshark": {
"command": "python",
"args": [
"/path/to/wireshark-mcp/mcp_server.py",
"--stdio"
]
}
}
}
```
Replace `/path/to/wireshark-mcp` with the actual path to your repository.
## Available Tools
The Wireshark MCP server provides the following tools:
- `capture_live_traffic`: Capture live network traffic using tshark
- `analyze_pcap`: Analyze an existing pcap file
- `get_protocol_list`: Get a list of supported protocols
## Example Usage in Claude
Once configured, you can use the Wireshark MCP server in Claude with queries like:
- "Capture 30 seconds of network traffic on my system and show me what's happening"
- "Analyze my network.pcap file and tell me if there are any suspicious activities"
- "What protocols can I focus on when analyzing network traffic?"
## Key Features
- **Packet Summarization**: Convert large pcap files into token-optimized summaries
- **Protocol Intelligence**: Enhanced context for common protocols (HTTP, DNS, TLS, SMTP, etc.)
- **Flow Tracking**: Group related packets into conversation flows
- **Anomaly Highlighting**: Emphasize unusual or suspicious patterns
- **Query Templates**: Pre-built prompts for common network analysis tasks
- **Visualization Generation**: Create text-based representations of network patterns
- **Multi-level Abstraction**: View data from raw bytes to high-level behaviors
- **Web Interface**: Browser-based UI for easier analysis and visualization
- **Agent-to-Agent (A2A) Integration**: Expose packet analysis as an A2A-compatible agent
- **Advanced Security Framework**: Comprehensive security controls for data protection and communication
- **IP Address Protection**: Multiple strategies for anonymizing sensitive network addresses
- **Secure Communication**: Robust message signatures for secure agent-to-agent communication
- **Cross-Platform**: Works on Windows, macOS, and Linux
## Documentation
- [Claude Integration Guide](docs/claude_integration.md) - Detailed guide for connecting with Claude AI
- [A2A Module Documentation](docs/a2a_module.md) - Guide for using the Agent-to-Agent integration
- [A2A Security Guide](docs/agent_to_agent_integration.md) - Security considerations for A2A integration
- [IP Protection Guide](docs/ip_protection.md) - Detailed guide on IP address anonymization and obfuscation
- [Security Manager Guide](docs/security_manager.md) - Comprehensive guide to the unified security framework
- [Message Security Signatures](docs/security_signature.md) - Guide for secure message signing and verification
- [Web Interface README](web_interface/README.md) - Information on using the web interface
- [Utility Scripts](scripts/README.md) - Helpful scripts for PCAP analysis
## Basic Usage
```python
from wireshark_mcp import WiresharkMCP, Protocol
from wireshark_mcp.formatters import ClaudeFormatter
# Initialize with a pcap file
mcp = WiresharkMCP("capture.pcap")
# Generate a basic packet summary
context = mcp.generate_context(
max_packets=100,
focus_protocols=[Protocol.HTTP, Protocol.DNS],
include_statistics=True
)
# Format it for Claude
formatter = ClaudeFormatter()
claude_prompt = formatter.format_context(
context,
query="What unusual patterns do you see in this HTTP traffic?"
)
# Save to file for use with Claude
with open("claude_prompt.md", "w") as f:
f.write(claude_prompt)
```
## Using with Claude
There are three main ways to use Wireshark MCP with Claude:
### 1. Direct MCP Integration (NEW)
For seamless integration with Claude Desktop:
```bash
# Run the MCP server with stdio transport
python mcp_server.py --stdio
```
Then configure Claude Desktop as described in the "Configuring Claude Desktop" section above. This method provides direct integration without any copy/paste needed.
### 2. Simple Script Approach
For quick analysis without complex setup (requires copy/paste):
```bash
python scripts/simple_pcap_analysis.py path/to/your/capture.pcap
```
This generates a markdown file you can copy and paste into Claude at [claude.ai](https://claude.ai).
### 3. API Integration
For programmatic integration with Claude's API:
```python
from claude_client import ClaudeClient # Your implementation
from wireshark_mcp import WiresharkMCP
from wireshark_mcp.formatters import ClaudeFormatter
# Process the PCAP file
mcp = WiresharkMCP("capture.pcap")
context = mcp.generate_context()
# Format for Claude
formatter = ClaudeFormatter()
prompt = formatter.format_context(context, query="Analyze this network traffic")
# Send to Claude API
client = ClaudeClient(api_key="your_api_key")
response = client.analyze(prompt)
```
See the [Claude Integration Guide](docs/claude_integration.md) for detailed API instructions.
## Requirements
- Python 3.8+
- Wireshark/tshark installed and in your PATH
- fastmcp Python package
## Contributing
Contributions are welcome! Areas where help is especially appreciated:
- Additional protocol analyzers
- Performance optimizations
- Documentation and examples
- Testing with diverse packet captures
- Web interface enhancements
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.