Sharkmcp

🚀 SharkMCP - Network Packet Analysis MCP Server

SharkMCP is a Model Context Protocol (MCP) server that integrates with Wireshark/tshark to offer network packet capture and analysis capabilities. It's tailored for AI assistants to conduct network security analysis, troubleshooting, and packet inspection.

🚀 Quick Start

This server is designed for scenarios where you need your agent to debug a program sending requests and verify packet traffic. The workflow is as follows:

1. Start recording packets.
2. Run a tool or perform a request.
3. Stop recording and analyze the results.

✨ Features

• Async Packet Capture: Initiate background capture sessions with configurable filters and timeouts.
• PCAP File Analysis: Analyze existing packet capture files.
• Flexible Output Formats: Support for JSON, custom fields, or traditional text output.
• SSL/TLS Decryption: Decrypt HTTPS traffic using SSL keylog files.
• Reusable Configurations: Save and reuse capture/analysis configurations.

⚠️ Important Note

Packet information can be extremely extensive. Use a scoped display filter to avoid overloading your conversation context.

📦 Installation

Prerequisites

System Requirements

• Wireshark/tshark: Must be installed and accessible.
• Node.js: Version 18 or higher.
• pnpm: Recommended package manager.

Installing Wireshark/tshark

• macOS (using Homebrew):

brew install wireshark

• Ubuntu/Debian:

sudo apt update
sudo apt install tshark wireshark-common

• Windows: Download from wireshark.org

Installation Steps

1. Clone the repository:

git clone https://github.com/kriztalz/SharkMCP.git
cd SharkMCP

2. Install dependencies:

pnpm install

3. Build the project:

pnpm run build

4. Run the server:

pnpm start

💻 Usage Examples

Available Tools

1. start_capture_session: Start background packet capture.
2. stop_capture_session: Stop capture and analyze results.
3. analyze_pcap_file: Analyze existing PCAP files.
4. manage_config: Save/load reusable configurations.

Basic Usage

Start a capture session

Interface: en0
Capture Filter: port 443
Timeout: 30 seconds

Analyze captured traffic

Display Filter: tls.handshake.type == 1
Output Format: json

Save a configuration

{
  "name": "https-monitoring",
  "description": "Monitor HTTPS traffic",
  "captureFilter": "port 443",
  "displayFilter": "tls.handshake.type == 1",
  "outputFormat": "json",
  "timeout": 60,
  "interface": "en0"
}

📚 Documentation

Architecture

SharkMCP has a simple architecture focused on local development:

┌─────────────────────────────────────────────────────────┐
│                    SharkMCP Server                      │
├─────────────────────────────────────────────────────────┤
│  MCP Protocol Layer                                     │
│  ├─ start_capture_session                               │
│  ├─ stop_capture_session                                │
│  ├─ analyze_pcap_file                                   │
│  └─ manage_config                                       │
├─────────────────────────────────────────────────────────┤
│  tshark Integration Layer                               │
│  ├─ Cross-platform executable detection                 │
│  ├─ Process management                                  │
│  └─ Output parsing (JSON/fields/text)                   │
├─────────────────────────────────────────────────────────┤
│  Host System Integration                                │
│  ├─ Local tshark installation                           │
│  ├─ Direct network interface access                     │
│  └─ Native file system operations                       │
└─────────────────────────────────────────────────────────┘

Configuration

MCP Client Setup

{
  "mcpServers": {
    "sharkmcp": {
      "command": "node",
      "args": ["/path/to/SharkMCP/dist/index.js"],
    }
  }
}

SSL/TLS Decryption (Optional)

To decrypt HTTPS traffic, export the SSLKEYLOGFILE environment variable:

export SSLKEYLOGFILE=/path/to/sslkeylog.log

Configure your applications to log SSL keys to this file. Many applications support this automatically when the environment variable is set. Then pass the log file pathname to the MCP server in the stop_capture_session tool.

Testing

SharkMCP includes comprehensive integration tests for packet capture functionality.

# Run all tests
pnpm test

Development

Project Structure

SharkMCP/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript interfaces
│   ├── utils.ts              # Utility functions
│   └── tools/                # Individual tool implementations
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # Test files
│   └── integration.test.js   # Integration tests
├── package.json
└── README.md

Development Commands

# Development mode with auto-reload
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run build

🔧 Technical Details

Security Considerations

• Network Permissions: Packet capture requires elevated privileges.
• File Access: Temporary files are created in /tmp/.
• Docker Security: The container runs as a non-root user.
• SSL Keylog: Handle sensitive SSL keys securely.

Troubleshooting

Common Issues

• "tshark not found":
  • Ensure Wireshark is installed and tshark is in PATH.
  • Check installation with: tshark -v.
• Permission denied for packet capture:
  • On Linux: Add the user to the wireshark group or run with sudo.
  • On macOS: Grant Terminal network access in System Preferences.
  • On Windows: Run as Administrator.
• No packets captured:
  • Verify the network interface name (ip link on Linux, ifconfig on macOS).
  • Check the capture filter syntax.
  • Ensure traffic is present on the interface.

🤝 Contributing (Very welcome!)

1. Fork the repository.
2. Create a feature branch.
3. Make changes following the existing code style.
4. Add tests for new functionality.
5. Submit a pull request.

📄 License

This project is under the MIT License.

💬 Issues / Suggestions

Feel free to open an issue for any questions or suggestions.