mcpcap 0.6.2

A modular Python MCP Server for analyzing PCAP files

mcpcap

A modular Python MCP (Model Context Protocol) server for analyzing PCAP files. mcpcap exposes protocol-specific analysis tools that accept a local file path or remote HTTP URL at call time, so the server stays stateless and works cleanly with MCP clients.

Overview

mcpcap uses a modular architecture to analyze different network protocols found in PCAP files. Each module provides specialized analysis tools that can be called independently with any PCAP file, making it perfect for integration with Claude Desktop and other MCP clients.

Key Features

• Stateless MCP Tools: Each analysis call supplies its own PCAP path or URL
• Modular Architecture: DNS, DHCP, ICMP, TCP, and CapInfos modules with easy extensibility for new protocols
• Advanced TCP Analysis: Connection lifecycle, traffic patterns, retransmissions, and flow inspection
• Local & Remote PCAP Support: Analyze files from local storage or HTTP URLs
• Scapy Integration: Leverages scapy's comprehensive packet parsing capabilities
• Specialized Analysis Prompts: Security, networking, and forensic analysis guidance
• JSON Responses: Structured data format optimized for LLM consumption

Installation

mcpcap requires Python 3.10 or greater.

Using pip

pip install mcpcap

Using uv

uv add mcpcap

Using uvx (for one-time usage)

uvx mcpcap

Quick Start

1. Start the MCP Server

Start mcpcap as a stateless MCP server:

# Default: Start with DNS, DHCP, ICMP, TCP, and CapInfos modules
mcpcap

# Start with specific modules only
mcpcap --modules dns,tcp

# With packet analysis limits
mcpcap --max-packets 1000

2. Connect Your MCP Client

Configure your MCP client (like Claude Desktop) to connect to the mcpcap server:

{
  "mcpServers": {
    "mcpcap": {
      "command": "mcpcap",
      "args": []
    }
  }
}

3. Analyze PCAP Files

Use the analysis tools with any PCAP file by providing the file path or URL when you call the tool:

DNS Analysis:

analyze_dns_packets("/path/to/dns.pcap")
analyze_dns_packets("https://example.com/remote.pcap")

DHCP Analysis:

analyze_dhcp_packets("/path/to/dhcp.pcap")
analyze_dhcp_packets("https://example.com/dhcp-capture.pcap")

ICMP Analysis:

analyze_icmp_packets("/path/to/icmp.pcap")
analyze_icmp_packets("https://example.com/ping-capture.pcap")

TCP Connection Analysis:

analyze_tcp_connections("/path/to/capture.pcap")
analyze_tcp_connections("/path/to/capture.pcap", server_ip="192.168.1.1", server_port=80)

TCP Pattern Analysis:

analyze_tcp_anomalies("/path/to/capture.pcap", server_ip="10.0.0.1")

TCP Retransmission Analysis:

analyze_tcp_retransmissions("/path/to/capture.pcap")

Traffic Flow Analysis:

analyze_traffic_flow("/path/to/capture.pcap", server_ip="192.168.1.100")

CapInfos Analysis:

analyze_capinfos("/path/to/any.pcap")
analyze_capinfos("https://example.com/capture.pcap")

Available Tools

DNS Analysis Tools

• analyze_dns_packets(pcap_file): Complete DNS traffic analysis
  • Extract DNS queries and responses
  • Identify queried domains and subdomains
  • Analyze query types (A, AAAA, MX, CNAME, etc.)
  • Track query frequency and patterns
  • Detect potential security issues

DHCP Analysis Tools

• analyze_dhcp_packets(pcap_file): Complete DHCP traffic analysis
  • Track DHCP transactions (DISCOVER, OFFER, REQUEST, ACK)
  • Identify DHCP clients and servers
  • Monitor IP address assignments and lease information
  • Analyze DHCP options and configurations
  • Detect DHCP anomalies and security issues

ICMP Analysis Tools

• analyze_icmp_packets(pcap_file): Complete ICMP traffic analysis
  • Analyze ping requests and replies with response times
  • Identify network connectivity and reachability issues
  • Track TTL values and routing paths (traceroute data)
  • Detect ICMP error messages (unreachable, time exceeded)
  • Monitor for potential ICMP-based attacks or reconnaissance

TCP Analysis Tools

• analyze_tcp_connections(pcap_file, server_ip=None, server_port=None, detailed=False): TCP connection state analysis

  • Track TCP three-way handshake (SYN, SYN-ACK, ACK)
  • Analyze connection lifecycle and termination (FIN, RST)
  • Identify successful vs failed connections
  • Filter by server IP and/or port
  • Detect connection issues and abnormal closures

• analyze_tcp_anomalies(pcap_file, server_ip=None, server_port=None): Observational TCP traffic analysis

  • Summarize handshakes, flags, resets, and retransmissions
  • Surface directional RST and retransmission patterns
  • Report connection lifecycle metrics
  • Return factual traffic patterns for further investigation

• analyze_tcp_retransmissions(pcap_file, server_ip=None, threshold=0.02): TCP retransmission analysis

  • Measure overall and per-connection retransmission rates
  • Identify connections with quality issues
  • Compare against configurable thresholds
  • Detect network congestion and packet loss

• analyze_traffic_flow(pcap_file, server_ip, server_port=None): Bidirectional traffic flow analysis

  • Analyze client-to-server vs server-to-client traffic
  • Identify traffic asymmetry
  • Determine RST packet sources
  • Interpret connection patterns and behaviors

CapInfos Analysis Tools

• analyze_capinfos(pcap_file): PCAP file metadata and statistics
  • File information (size, name, link layer encapsulation)
  • Packet statistics (count, data size, average packet size)
  • Temporal analysis (duration, timestamps, packet rates)
  • Data throughput metrics (bytes/second, bits/second)
  • Similar to Wireshark's capinfos(1) utility

Analysis Prompts

mcpcap provides specialized analysis prompts to guide LLM analysis:

DNS Prompts

• security_analysis - Focus on threat detection, DGA domains, DNS tunneling
• network_troubleshooting - Identify DNS performance and configuration issues
• forensic_investigation - Timeline reconstruction and evidence collection

DHCP Prompts

• dhcp_network_analysis - Network administration and IP management
• dhcp_security_analysis - Security threats and rogue DHCP detection
• dhcp_forensic_investigation - Forensic analysis of DHCP transactions

ICMP Prompts

• icmp_network_diagnostics - Network connectivity and path analysis
• icmp_security_analysis - ICMP-based attacks and reconnaissance detection
• icmp_forensic_investigation - Timeline reconstruction and network mapping

TCP Prompts

• tcp_connection_troubleshooting - Connection issues, handshake analysis, termination patterns
• tcp_security_analysis - Attack detection, firewall analysis, anomaly identification

Configuration Options

Module Selection

# Load specific modules
mcpcap --modules dns              # DNS analysis only
mcpcap --modules tcp              # TCP analysis only
mcpcap --modules dhcp             # DHCP analysis only
mcpcap --modules icmp             # ICMP analysis only  
mcpcap --modules dns,tcp          # DNS and TCP analysis
mcpcap --modules dns,dhcp,icmp,tcp,capinfos    # All modules (default)

Analysis Limits

# Limit packet analysis for large files
mcpcap --max-packets 1000

Complete Configuration Example

mcpcap --modules dns,dhcp,icmp,tcp,capinfos --max-packets 500

CLI Reference

mcpcap [--modules MODULES] [--max-packets N]

Options:

• --modules MODULES: Comma-separated modules to load (default: dns,dhcp,icmp,tcp,capinfos)
  • Available modules: dns, dhcp, icmp, tcp, capinfos
• --max-packets N: Maximum packets to analyze per file (default: unlimited)

Examples:

# Start with all modules
mcpcap

# DNS and TCP analysis only
mcpcap --modules dns,tcp

# TCP analysis for troubleshooting connections
mcpcap --modules tcp

# With packet limits for large files
mcpcap --max-packets 1000

Examples

Example PCAP files are included in the examples/ directory:

• dns.pcap - DNS traffic for testing DNS analysis
• dhcp.pcap - DHCP 4-way handshake capture

There is currently no bundled ICMP sample capture in examples/.

Using with MCP Inspector

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector mcpcap

Then test the tools:

// In the MCP Inspector web interface
analyze_dns_packets("./examples/dns.pcap")
analyze_dhcp_packets("./examples/dhcp.pcap")
analyze_capinfos("./examples/dns.pcap")
analyze_tcp_connections("/absolute/path/to/capture.pcap")

Architecture

mcpcap's modular design supports easy extension:

Core Components

1. BaseModule: Shared file handling, validation, and remote download
2. Protocol Modules: DNS, DHCP, ICMP, TCP, and CapInfos implementations
3. MCP Interface: Tool registration and prompt management
4. FastMCP Framework: MCP server implementation

Tool Flow

MCP Client Request → analyze_*_packets(pcap_file)
                  → BaseModule.analyze_packets()
                  → Module._analyze_protocol_file()
                  → Structured JSON Response

Adding New Modules

Create new protocol modules by:

1. Inheriting from BaseModule
2. Implementing _analyze_protocol_file(pcap_file)
3. Registering analysis tools with the MCP server
4. Adding specialized analysis prompts

Future modules might include:

• HTTP/HTTPS traffic analysis
• UDP connection analysis
• BGP routing analysis
• SSL/TLS certificate analysis
• Network forensics tools
• Port scan detection

Remote File Support

Both analysis tools accept remote PCAP files via HTTP/HTTPS URLs:

# Examples of remote analysis
analyze_dns_packets("https://wiki.wireshark.org/uploads/dns.cap")
analyze_dhcp_packets("https://example.com/network-capture.pcap")
analyze_icmp_packets("https://example.com/ping-test.pcap")
analyze_capinfos("https://example.com/network-metadata.pcap")
analyze_tcp_connections("https://example.com/tcp-session.pcap")

Features:

• Automatic temporary download and cleanup
• Support for .pcap, .pcapng, and .cap files
• HTTP/HTTPS protocols supported

Security Considerations

When analyzing PCAP files:

• Files may contain sensitive network information
• Remote downloads are performed over HTTPS when possible
• Temporary files are cleaned up automatically
• Consider the source and trustworthiness of remote files

Contributing

Contributions welcome! Areas for contribution:

• New Protocol Modules: Add support for HTTP, BGP, TCP, etc.
• Enhanced Analysis: Improve existing DNS/DHCP analysis
• Security Features: Add more threat detection capabilities
• Performance: Optimize analysis for large PCAP files

License

MIT

Requirements

• Python 3.10+
• scapy (packet parsing and analysis)
• requests (remote file access)
• fastmcp (MCP server framework)

Documentation

• GitHub: github.com/mcpcap/mcpcap
• Documentation: docs.mcpcap.ai
• Website: mcpcap.ai

Support

For questions, issues, or feature requests, please open an issue on GitHub.