{
  "markdown": "# mcpcap\n\n<!-- mcp-name: ai.mcpcap/mcpcap -->\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/mcpcap/mcpcap/main/readme-assets/mcpcap-logo.png\" alt=\"mcpcap logo\" width=\"240\" />\n</p>\n\nA 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.\n\n## Overview\n\nmcpcap 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.\n\n### Key Features\n\n- **Stateless MCP Tools**: Each analysis call supplies its own PCAP path or URL\n- **Modular Architecture**: DNS, DHCP, ICMP, TCP, SIP, and CapInfos modules with easy extensibility for new protocols\n- **Advanced TCP Analysis**: Connection lifecycle, traffic patterns, retransmissions, and flow inspection\n- **Local & Remote PCAP Support**: Analyze files from local storage or HTTP URLs\n- **Scapy Integration**: Leverages scapy's comprehensive packet parsing capabilities\n- **Specialized Analysis Prompts**: Security, networking, and forensic analysis guidance\n- **JSON Responses**: Structured data format optimized for LLM consumption\n\n## Installation\n\nmcpcap requires Python 3.10 or greater.\n\n### Using pip\n\n```bash\npip install mcpcap\n```\n\n### Using uv\n\n```bash\nuv add mcpcap\n```\n\n### Using uvx (for one-time usage)\n\n```bash\nuvx mcpcap\n```\n\n### Using Docker\n\nBuild the image from the repository root:\n\n```bash\ndocker build -t mcpcap .\n```\n\nRun it over HTTP for MCP clients that connect to a network endpoint:\n\n```bash\ndocker run --rm \\\n  -p 8080:8080 \\\n  -v \"$(pwd)/examples:/pcaps:ro\" \\\n  mcpcap --transport http --host 0.0.0.0 --port 8080\n```\n\nRun it over stdio for clients that can spawn `docker run` directly:\n\n```bash\ndocker run --rm -i \\\n  -v \"$(pwd)/examples:/pcaps:ro\" \\\n  mcpcap\n```\n\nWhen you mount local captures into the container, use the container path in tool calls:\n\n```text\nanalyze_dns_packets(\"/pcaps/dns.pcap\")\n```\n\nRemote `http://` and `https://` PCAP URLs work without a volume mount because mcpcap downloads them inside the container at call time.\n\n### Using Docker Compose\n\nFor the default HTTP workflow, start the bundled Compose service:\n\n```bash\ndocker compose up\n```\n\nThis pulls `ghcr.io/mcpcap/mcpcap:latest`, publishes `http://127.0.0.1:8080/mcp`, and mounts `./examples` into the container as `/pcaps`.\n\n```text\nanalyze_dns_packets(\"/pcaps/dns.pcap\")\n```\n\nTo analyze your own captures, change the volume in [docker-compose.yml](/Users/daniel/.codex/worktrees/4c5f/mcpcap/docker-compose.yml) from `./examples:/pcaps:ro` to your local capture directory.\n\nFor local development against the checked-out source instead of GHCR:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml up --build\n```\n\n## Quick Start\n\n### 1. Start the MCP Server\n\nStart mcpcap as a stateless MCP server:\n\n```bash\n# Default stdio transport for Claude Desktop and similar clients\nmcpcap\n\n# Start with specific modules only\nmcpcap --modules dns,tcp\n\n# With packet analysis limits\nmcpcap --max-packets 1000\n\n# Start an HTTP transport server for remote MCP clients\nmcpcap --transport http --host 127.0.0.1 --port 8080\n```\n\n### 2. Connect Your MCP Client\n\nUse stdio transport for local MCP clients like Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpcap\": {\n      \"command\": \"mcpcap\",\n      \"args\": []\n    }\n  }\n}\n```\n\nUse HTTP transport when your MCP client expects a network endpoint:\n\n```bash\nmcpcap --transport http --host 127.0.0.1 --port 8080\n```\n\nPoint your HTTP-capable MCP client at:\n\n```text\nhttp://127.0.0.1:8080/mcp\n```\n\nDocker users can publish the same endpoint with:\n\n```bash\ndocker run --rm \\\n  -p 8080:8080 \\\n  -v \"/path/to/captures:/pcaps:ro\" \\\n  mcpcap --transport http --host 0.0.0.0 --port 8080\n```\n\nOr with Compose:\n\n```bash\ndocker compose up\n```\n\n### 3. Analyze PCAP Files\n\nUse the analysis tools with any PCAP file by providing the file path or URL when you call the tool:\n\n**DNS Analysis:**\n```\nanalyze_dns_packets(\"/path/to/dns.pcap\")\nanalyze_dns_packets(\"https://example.com/remote.pcap\")\n```\n\n**DHCP Analysis:**\n```\nanalyze_dhcp_packets(\"/path/to/dhcp.pcap\")\nanalyze_dhcp_packets(\"https://example.com/dhcp-capture.pcap\")\n```\n\n**ICMP Analysis:**\n```\nanalyze_icmp_packets(\"/path/to/icmp.pcap\")\nanalyze_icmp_packets(\"https://example.com/ping-capture.pcap\")\n```\n\n**TCP Connection Analysis:**\n```\nanalyze_tcp_connections(\"/path/to/capture.pcap\")\nanalyze_tcp_connections(\"/path/to/capture.pcap\", server_ip=\"192.168.1.1\", server_port=80)\n```\n\n**TCP Pattern Analysis:**\n```\nanalyze_tcp_anomalies(\"/path/to/capture.pcap\", server_ip=\"10.0.0.1\")\n```\n\n**TCP Retransmission Analysis:**\n```\nanalyze_tcp_retransmissions(\"/path/to/capture.pcap\")\n```\n\n**Traffic Flow Analysis:**\n```\nanalyze_traffic_flow(\"/path/to/capture.pcap\", server_ip=\"192.168.1.100\")\n```\n\n**SIP Analysis:**\n```\nanalyze_sip_packets(\"/path/to/voip-signaling.pcap\")\nanalyze_sip_packets(\"https://example.com/sip-call-flow.pcap\")\n```\n\n**CapInfos Analysis:**\n```\nanalyze_capinfos(\"/path/to/any.pcap\")\nanalyze_capinfos(\"https://example.com/capture.pcap\")\n```\n\nIf you are using Docker with a bind mount, pass the in-container path instead of the host path:\n\n```text\nanalyze_capinfos(\"/pcaps/dns.pcap\")\n```\n\n## Available Tools\n\n### DNS Analysis Tools\n\n- **`analyze_dns_packets(pcap_file)`**: Complete DNS traffic analysis\n  - Extract DNS queries and responses\n  - Identify queried domains and subdomains\n  - Analyze query types (A, AAAA, MX, CNAME, etc.)\n  - Track query frequency and patterns\n  - Detect potential security issues\n\n### DHCP Analysis Tools\n\n- **`analyze_dhcp_packets(pcap_file)`**: Complete DHCP traffic analysis\n  - Track DHCP transactions (DISCOVER, OFFER, REQUEST, ACK)\n  - Identify DHCP clients and servers\n  - Monitor IP address assignments and lease information\n  - Analyze DHCP options and configurations\n  - Detect DHCP anomalies and security issues\n\n### ICMP Analysis Tools\n\n- **`analyze_icmp_packets(pcap_file)`**: Complete ICMP traffic analysis\n  - Analyze ping requests and replies with response times\n  - Identify network connectivity and reachability issues\n  - Track TTL values and routing paths (traceroute data)\n  - Detect ICMP error messages (unreachable, time exceeded)\n  - Monitor for potential ICMP-based attacks or reconnaissance\n\n### TCP Analysis Tools\n\n- **`analyze_tcp_connections(pcap_file, server_ip=None, server_port=None, detailed=False)`**: TCP connection state analysis\n  - Track TCP three-way handshake (SYN, SYN-ACK, ACK)\n  - Analyze connection lifecycle and termination (FIN, RST)\n  - Identify successful vs failed connections\n  - Filter by server IP and/or port\n  - Detect connection issues and abnormal closures\n\n- **`analyze_tcp_anomalies(pcap_file, server_ip=None, server_port=None)`**: Observational TCP traffic analysis\n  - Summarize handshakes, flags, resets, and retransmissions\n  - Surface directional RST and retransmission patterns\n  - Report connection lifecycle metrics\n  - Return factual traffic patterns for further investigation\n\n- **`analyze_tcp_retransmissions(pcap_file, server_ip=None, threshold=0.02)`**: TCP retransmission analysis\n  - Measure overall and per-connection retransmission rates\n  - Identify connections with quality issues\n  - Compare against configurable thresholds\n  - Detect network congestion and packet loss\n\n- **`analyze_traffic_flow(pcap_file, server_ip, server_port=None)`**: Bidirectional traffic flow analysis\n  - Analyze client-to-server vs server-to-client traffic\n  - Identify traffic asymmetry\n  - Determine RST packet sources\n  - Interpret connection patterns and behaviors\n\n### SIP Analysis Tools\n\n- **`analyze_sip_packets(pcap_file)`**: SIP signaling analysis\n  - Parse SIP requests and responses across UDP and TCP transports\n  - Extract call identifiers, CSeq values, endpoints, and key signaling headers\n  - Summarize request methods and response code classes\n  - Surface user agents, signaling servers, and transport usage\n  - Support VoIP troubleshooting, security review, and forensic reconstruction\n\n### CapInfos Analysis Tools\n\n- **`analyze_capinfos(pcap_file)`**: PCAP file metadata and statistics\n  - File information (size, name, link layer encapsulation)\n  - Packet statistics (count, data size, average packet size)\n  - Temporal analysis (duration, timestamps, packet rates)\n  - Data throughput metrics (bytes/second, bits/second)\n  - Similar to Wireshark's capinfos(1) utility\n\n## Analysis Prompts\n\nmcpcap provides specialized analysis prompts to guide LLM analysis:\n\n### DNS Prompts\n- **`security_analysis`** - Focus on threat detection, DGA domains, DNS tunneling\n- **`network_troubleshooting`** - Identify DNS performance and configuration issues\n- **`forensic_investigation`** - Timeline reconstruction and evidence collection\n\n### DHCP Prompts\n- **`dhcp_network_analysis`** - Network administration and IP management\n- **`dhcp_security_analysis`** - Security threats and rogue DHCP detection\n- **`dhcp_forensic_investigation`** - Forensic analysis of DHCP transactions\n\n### ICMP Prompts\n- **`icmp_network_diagnostics`** - Network connectivity and path analysis\n- **`icmp_security_analysis`** - ICMP-based attacks and reconnaissance detection\n- **`icmp_forensic_investigation`** - Timeline reconstruction and network mapping\n\n### TCP Prompts\n- **`tcp_connection_troubleshooting`** - Connection issues, handshake analysis, termination patterns\n- **`tcp_security_analysis`** - Attack detection, firewall analysis, anomaly identification\n\n### SIP Prompts\n- **`sip_security_analysis`** - Registration abuse, toll fraud, and signaling exposure review\n- **`sip_troubleshooting_analysis`** - Call setup progression, routing mismatches, and response-code failures\n- **`sip_forensic_investigation`** - Timeline reconstruction by Call-ID, CSeq, endpoint, and transport\n\n## Configuration Options\n\n### Module Selection\n\n```bash\n# Load specific modules\nmcpcap --modules dns              # DNS analysis only\nmcpcap --modules tcp              # TCP analysis only\nmcpcap --modules dhcp             # DHCP analysis only\nmcpcap --modules icmp             # ICMP analysis only\nmcpcap --modules sip              # SIP analysis only\nmcpcap --modules dns,tcp          # DNS and TCP analysis\nmcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos    # All modules (default)\n```\n\n### Analysis Limits\n\n```bash\n# Limit packet analysis for large files\nmcpcap --max-packets 1000\n```\n\n### Transport Options\n\n```bash\n# Default stdio transport\nmcpcap\n\n# HTTP transport for network-accessible MCP clients\nmcpcap --transport http\n\n# HTTP transport on a custom interface and port\nmcpcap --transport http --host 0.0.0.0 --port 9000\n```\n\n### Complete Configuration Example\n\n```bash\nmcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos --max-packets 500\n```\n\n## CLI Reference\n\n```bash\nmcpcap [--modules MODULES] [--max-packets N] [--transport {stdio,http}] [--host HOST] [--port PORT]\n```\n\n**Options:**\n- `--modules MODULES`: Comma-separated modules to load (default: `dns,dhcp,icmp,tcp,sip,capinfos`)\n  - Available modules: `dns`, `dhcp`, `icmp`, `tcp`, `sip`, `capinfos`\n- `--max-packets N`: Maximum packets to analyze per file (default: unlimited)\n- `--transport {stdio,http}`: MCP transport to expose (default: `stdio`)\n- `--host HOST`: Host to bind for HTTP transport (default: `127.0.0.1`)\n- `--port PORT`: Port to bind for HTTP transport (default: `8080`)\n\n**Examples:**\n```bash\n# Start with all modules\nmcpcap\n\n# DNS and TCP analysis only\nmcpcap --modules dns,tcp\n\n# TCP analysis for troubleshooting connections\nmcpcap --modules tcp\n\n# With packet limits for large files\nmcpcap --max-packets 1000\n\n# Expose mcpcap over HTTP\nmcpcap --transport http --host 127.0.0.1 --port 8080\n```\n\n## Examples\n\nExample PCAP files are included in the `examples/` directory:\n\n- `dns.pcap` - DNS traffic for testing DNS analysis\n- `dhcp.pcap` - DHCP 4-way handshake capture\n\nThere is currently no bundled ICMP sample capture in `examples/`.\n\n### Using with MCP Inspector\n\n```bash\nnpm install -g @modelcontextprotocol/inspector\nnpx @modelcontextprotocol/inspector mcpcap\n```\n\nThen test the tools:\n```javascript\n// In the MCP Inspector web interface\nanalyze_dns_packets(\"./examples/dns.pcap\")\nanalyze_dhcp_packets(\"./examples/dhcp.pcap\")\nanalyze_capinfos(\"./examples/dns.pcap\")\nanalyze_tcp_connections(\"/absolute/path/to/capture.pcap\")\nanalyze_sip_packets(\"/absolute/path/to/voip-signaling.pcap\")\n```\n\n## Architecture\n\nmcpcap's modular design supports easy extension:\n\n### Core Components\n1. **BaseModule**: Shared file handling, validation, and remote download\n2. **Protocol Modules**: DNS, DHCP, ICMP, TCP, SIP, and CapInfos implementations\n3. **MCP Interface**: Tool registration and prompt management\n4. **FastMCP Framework**: MCP server implementation\n\n### Tool Flow\n```\nMCP Client Request → analyze_*_packets(pcap_file)\n                  → BaseModule.analyze_packets()\n                  → Module._analyze_protocol_file()\n                  → Structured JSON Response\n```\n\n### Adding New Modules\n\nCreate new protocol modules by:\n\n1. Inheriting from `BaseModule`\n2. Implementing `_analyze_protocol_file(pcap_file)`\n3. Registering analysis tools with the MCP server\n4. Adding specialized analysis prompts\n\nFuture modules might include:\n- HTTP/HTTPS traffic analysis\n- UDP connection analysis\n- BGP routing analysis\n- SSL/TLS certificate analysis\n- Network forensics tools\n- Port scan detection\n\n## Remote File Support\n\nBoth analysis tools accept remote PCAP files via HTTP/HTTPS URLs:\n\n```bash\n# Examples of remote analysis\nanalyze_dns_packets(\"https://raw.githubusercontent.com/mcpcap/mcpcap/main/examples/dns.pcap\")\nanalyze_dhcp_packets(\"https://example.com/network-capture.pcap\")\nanalyze_icmp_packets(\"https://example.com/ping-test.pcap\")\nanalyze_capinfos(\"https://example.com/network-metadata.pcap\")\nanalyze_tcp_connections(\"https://example.com/tcp-session.pcap\")\nanalyze_sip_packets(\"https://example.com/sip-signaling.pcap\")\n```\n\n**Features:**\n- Automatic temporary download and cleanup\n- Support for `.pcap`, `.pcapng`, and `.cap` files\n- HTTP/HTTPS protocols supported\n\n## Security Considerations\n\nWhen analyzing PCAP files:\n- Files may contain sensitive network information\n- Remote downloads are performed over HTTPS when possible\n- Temporary files are cleaned up automatically\n- Consider the source and trustworthiness of remote files\n\n## Contributing\n\nContributions welcome! Areas for contribution:\n\n- **New Protocol Modules**: Add support for HTTP, BGP, TLS, RTP, etc.\n- **Enhanced Analysis**: Improve existing DNS/DHCP analysis\n- **Security Features**: Add more threat detection capabilities\n- **Performance**: Optimize analysis for large PCAP files\n\n## License\n\nMIT\n\n## Requirements\n\n- Python 3.10+\n- scapy (packet parsing and analysis)\n- requests (remote file access)\n- fastmcp (MCP server framework)\n\n## Documentation\n\n- **GitHub**: [github.com/mcpcap/mcpcap](https://github.com/mcpcap/mcpcap)\n- **Documentation**: [docs.mcpcap.ai](https://docs.mcpcap.ai)\n- **Website**: [mcpcap.ai](https://mcpcap.ai)\n\n## Support\n\nFor questions, issues, or feature requests, please open an issue on GitHub.\n",
  "bytes": 15326,
  "sha": "b69aab70878bd42b6b3edafbb7c4508fbf8f7b26026607b4274a3e537a60dcc5",
  "repo_slug": "mcpcap/mcpcap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_mcpcap_mcpcap_2957aec2/readme"
}