---

🚀 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.

---

✨ 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:

Category	Tools	Description
📡 Capture & Analysis	5	get_network_interfaces · capture_live_packets · quick_capture · save_capture_to_file · analyze_large_pcap
🔬 Protocol Analysis	10	analyze_pcap_file · get_protocol_statistics · get_capture_file_info · capture_targeted_traffic · analyze_http_traffic · detect_network_protocols · analyze_http_headers · geoip_lookup · analyze_dns_traffic · get_expert_info
📊 Network Flows	2	visualize_network_flows (ASCII + Mermaid) · decrypt_tls_traffic
🔧 PCAP Tools	4	diff_pcap_files · merge_pcap_files · slice_pcap · decode_packet
🔄 Streams	3	follow_tcp_stream · follow_udp_stream · list_tcp_streams
📤 Export	3	export_packets_json · export_packets_csv · convert_pcap_format
🔍 Nmap	6	nmap_port_scan · nmap_service_detection · nmap_os_detection · nmap_vulnerability_scan · nmap_quick_scan · nmap_comprehensive_scan
🛡️ Security	3	extract_credentials · check_ip_threat_intel · scan_capture_for_threats
🎨 Wireshark Profiles	4	list_wireshark_profiles · apply_profile_capture · get_color_filters · capture_with_profile

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

---

🔌 Transport Options

NetMCP supports all MCP transport protocols:

Transport	Command	Use Case
stdio (default)	netmcp	Claude Desktop, Cursor, local clients
SSE	netmcp --transport sse	Web-based clients, remote access
Streamable HTTP	netmcp --transport streamable-http	Modern HTTP clients

---

⚙️ 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

Variable	Required	Default	Description
ABUSEIPDB_API_KEY	No	—	AbuseIPDB API key for threat intelligence. Get free key
NETMCP_TSHARK_PATH	No	Auto-detect	Custom path to tshark binary
NETMCP_MAX_PACKETS	No	10000	Maximum packets per capture operation
NETMCP_MAX_FILE_SIZE	No	104857600	Maximum PCAP file size in bytes (100 MB)

---

📋 Requirements

Dependency	Required	Install
Python	3.11+	sudo apt install python3.11
TShark	Yes	sudo apt install tshark
Nmap	Optional	sudo apt install nmap

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:

Layer	Mechanism	Prevents
1. Input Validation	Regex, ipaddress module, Pydantic	Malformed input, injection payloads
2. Command Construction	List args, shell=False everywhere	Command injection, shell expansion
3. Subprocess Execution	Timeouts, captured output only	Runaway processes, resource exhaustion
4. File System	Path.resolve(), extension allowlist, size limits	Path traversal, symlink attacks
5. Rate Limiting	Sliding window, per-operation tracking	Abuse, DoS attacks

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

URI	Description
netmcp://interfaces	Dynamic list of available network interfaces
netmcp://captures	Available PCAP files in common directories
netmcp://system/info	System capabilities: tool versions, features

Prompts (Guided Workflows)

Prompt	Description
security_audit	Comprehensive PCAP security analysis with IOC extraction
network_troubleshooting	Step-by-step network diagnostics
incident_response	Security incident investigation workflow
traffic_analysis	Deep traffic analysis with GeoIP mapping
network_baseline	Establish normal traffic patterns

---

🧪 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

---