🌐 NetMCP

Professional-grade network analysis MCP server — Wireshark/TShark + Nmap + Threat Intelligence

NetMCP bridges the gap between raw network data and AI comprehension. It gives Claude, Cursor, and any MCP-compliant client the ability to capture packets, scan networks, detect threats, and extract credentials — all through natural language.

Quick Start • Features • Configuration • API Reference • Architecture

🚀 Quick Start

# Install system dependencies
sudo apt-get install -y tshark nmap        # Ubuntu/Debian
# brew install wireshark nmap              # macOS

# Install NetMCP
pip install netmcp

# Run
netmcp

That's it. The server starts on stdio transport by default, ready for any MCP client.

Related MCP server: Wireshark MCP

✨ Features

• 📡 Packet Capture — Live capture, BPF filtering, targeted traffic, quick capture mode

• 🔬 Deep Analysis — PCAP parsing, protocol statistics, HTTP traffic analysis, DNS analysis, expert info, GeoIP enrichment

• 🔄 Stream Reconstruction — Follow TCP/UDP conversations, enumerate streams

• 📤 Flexible Export — JSON, CSV, pcap/pcapng format conversion

• 🔍 Nmap Integration — Port scan, service detection, OS fingerprinting, vulnerability scan

• 🛡️ Threat Intelligence — URLhaus + AbuseIPDB IP reputation checks, PCAP-wide threat scan

• 🔑 Credential Extraction — HTTP Basic, FTP, Telnet, Kerberos (hashcat-ready)

• 🌍 GeoIP Mapping — MaxMind GeoLite2 IP geolocation for traffic analysis

• 🔒 5-Layer Security — Input validation, shell=False, rate limiting, path traversal protection, audit logging

• 💬 Guided Workflows — Security audit, incident response, troubleshooting, traffic analysis, network baseline prompts

Advanced Features

• 🔀 PCAP Diff/Merge/Slice — Compare captures, combine files via mergecap, extract packet ranges via editcap

• 📊 Flow Visualization — ASCII art and Mermaid sequence diagrams of network conversations

• 🔓 TLS Decryption — Decrypt HTTPS traffic using SSLKEYLOGFILE (NSS Key Log Format)

• 🎨 Wireshark Profiles — List profiles, apply profile settings, parse color filters, capture with profile

• 🧬 DNS Tunneling Detection — Analyze DNS traffic and flag suspiciously long subdomain names

• 📦 Packet Decode — Detailed single-packet analysis with full protocol layer dissection

• 🏥 Expert Information — Extract Wireshark's expert warnings, errors, and protocol violation notes

📊 Tool Categories

NetMCP provides 48 tools across 9 categories, plus 3 resources and 5 prompts:

📖 Full API reference with parameters and examples: docs/API.md

🔌 Transport Options

NetMCP supports all MCP transport protocols:

⚙️ Configuration

Claude Desktop

Edit your config 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": {
    "netmcp": {
      "command": "netmcp",
      "env": {
        "ABUSEIPDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "netmcp": {
      "command": "netmcp"
    }
  }
}

Windsurf / VS Code

Edit .vscode/mcp.json:

{
  "servers": {
    "netmcp": {
      "command": "netmcp",
      "env": {
        "ABUSEIPDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Environment Variables

📋 Requirements

macOS

brew install wireshark nmap

Linux Permissions

# Option 1: Set capabilities (recommended)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Option 2: Add user to wireshark group
sudo usermod -aG wireshark $USER && newgrp wireshark

🛡️ Security Model

NetMCP implements 5 layers of defense in depth:

Additional protections:

• 🔒 Never auto-escalates privileges

• 📝 All operations audit-logged with timestamps

• 🚫 Dangerous nmap flags rejected (--script-args, --interactive, etc.)

• ⚠️ Clear error messages for permission issues

🎯 Usage Examples

Live Packet Capture

You: Capture 100 packets from eth0 and analyze the protocols.

Claude: [capture_live_packets(interface="eth0", packet_count=100)]
       [get_protocol_statistics(filepath="capture.pcap")]
       Found 8 protocols: TCP (62%), UDP (24%), DNS (8%), HTTP (4%)...

Security Audit

You: Perform a security audit on suspicious.pcap

Claude: 1. [get_protocol_statistics] → traffic breakdown
        2. [extract_credentials] → found HTTP Basic Auth credentials
        3. [scan_capture_for_threats] → 2 malicious IPs detected
        4. Generated full security report with IOCs

Nmap Vulnerability Scan

You: Scan 192.168.1.100 for vulnerabilities

Claude: [nmap_quick_scan("192.168.1.100")] → ports 22, 80, 443 open
        [nmap_service_detection("192.168.1.100")] → nginx 1.18.0, OpenSSH 8.2
        [nmap_vulnerability_scan("192.168.1.100")] → no critical CVEs found

🧠 MCP Resources & Prompts

Resources

Prompts (Guided Workflows)

🧪 Development

# Clone and setup
git clone https://github.com/cortexc0de/netmcp.git
cd netmcp
python -m venv .venv
source .venv/bin/activate

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

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=netmcp --cov-report=html

# Linting
ruff check src/netmcp/ tests/
ruff format --check src/netmcp/
mypy src/netmcp/

Project Structure

src/netmcp/
├── server.py                # FastMCP server entry point
├── core/
│   ├── security.py          # 5-layer input validation + rate limiting
│   └── formatter.py         # MCP response formatting
├── interfaces/
│   ├── tshark.py            # TShark async CLI wrapper
│   ├── nmap.py              # python-nmap wrapper
│   └── threat_intel.py      # URLhaus + AbuseIPDB clients
├── tools/                   # 48 MCP tools across 11 modules
├── resources/               # 3 MCP resources
└── prompts/                 # 5 MCP prompts

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

1. Fork the repository

2. Create a feature branch (git checkout -b feat/amazing-feature)

3. Run tests (pytest tests/ -v)

4. Submit a Pull Request

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

• Wireshark/TShark — packet analysis toolkit

• Nmap — network scanner

• URLhaus & AbuseIPDB — threat intelligence

• Model Context Protocol — AI tool framework

Transform your network analysis with AI-powered packet capture, scanning, and threat intelligence.