mcpcap

Name	mcpcap JSON
Version	0.5.10 JSON
	download
home_page	None
Summary	A modular Python MCP Server for analyzing PCAP files
upload_time	2025-09-12 05:10:50
maintainer	None
docs_url	None
author	mcpcap contributors
requires_python	>=3.10
license	MIT License Copyright (c) 2025 danohn Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	pcap network analysis mcp dns
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # mcpcap

<!-- mcp-name: ai.mcpcap/mcpcap -->

![mcpcap logo](https://raw.githubusercontent.com/mcpcap/mcpcap/main/readme-assets/mcpcap-logo.png)

A modular Python MCP (Model Context Protocol) Server for analyzing PCAP files. mcpcap enables LLMs to read and analyze network packet captures with protocol-specific analysis tools that accept local files or remote URLs as parameters.

## 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 accepts PCAP file paths or URLs as parameters
- **Modular Architecture**: DNS, DHCP, and ICMP modules with easy extensibility for new protocols  
- **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

```bash
pip install mcpcap
```

### Using uv

```bash
uv add mcpcap
```

### Using uvx (for one-time usage)

```bash
uvx mcpcap
```

## Quick Start

### 1. Start the MCP Server

Start mcpcap as a stateless MCP server:

```bash
# Default: Start with DNS, DHCP, and ICMP modules
mcpcap

# Start with specific modules only
mcpcap --modules dns

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

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

### 3. Analyze PCAP Files

Use the analysis tools with any PCAP file:

**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")
```

## 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

## 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

## Configuration Options

### Module Selection

```bash
# Load specific modules
mcpcap --modules dns              # DNS analysis only
mcpcap --modules dhcp             # DHCP analysis only
mcpcap --modules icmp             # ICMP analysis only  
mcpcap --modules dns,dhcp,icmp    # All modules (default)
```

### Analysis Limits

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

### Complete Configuration Example

```bash
mcpcap --modules dns,dhcp,icmp --max-packets 500
```

## CLI Reference

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

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

**Examples:**
```bash
# Start with all modules
mcpcap

# DNS analysis only
mcpcap --modules dns

# 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
- `icmp.pcap` - ICMP ping and traceroute traffic

### Using with MCP Inspector

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

Then test the tools:
```javascript
// In the MCP Inspector web interface
analyze_dns_packets("./examples/dns.pcap")
analyze_dhcp_packets("./examples/dhcp.pcap")
analyze_icmp_packets("./examples/icmp.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, and ICMP analysis 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
- TCP connection tracking  
- BGP routing analysis
- SSL/TLS certificate analysis
- Network forensics tools

## Remote File Support

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

```bash
# 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")
```

**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](https://github.com/mcpcap/mcpcap)
- **Documentation**: [docs.mcpcap.ai](https://docs.mcpcap.ai) 
- **Website**: [mcpcap.ai](https://mcpcap.ai)

## Support

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

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mcpcap",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "pcap, network, analysis, mcp, dns",
    "author": "mcpcap contributors",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/24/cc/70d3f86993c60279f00ef947779c7197b17eebc97967220cf8ddc44e2663/mcpcap-0.5.10.tar.gz",
    "platform": null,
    "description": "# mcpcap\n\n<!-- mcp-name: ai.mcpcap/mcpcap -->\n\n![mcpcap logo](https://raw.githubusercontent.com/mcpcap/mcpcap/main/readme-assets/mcpcap-logo.png)\n\nA modular Python MCP (Model Context Protocol) Server for analyzing PCAP files. mcpcap enables LLMs to read and analyze network packet captures with protocol-specific analysis tools that accept local files or remote URLs as parameters.\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 accepts PCAP file paths or URLs as parameters\n- **Modular Architecture**: DNS, DHCP, and ICMP modules with easy extensibility for new protocols  \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## Quick Start\n\n### 1. Start the MCP Server\n\nStart mcpcap as a stateless MCP server:\n\n```bash\n# Default: Start with DNS, DHCP, and ICMP modules\nmcpcap\n\n# Start with specific modules only\nmcpcap --modules dns\n\n# With packet analysis limits\nmcpcap --max-packets 1000\n```\n\n### 2. Connect Your MCP Client\n\nConfigure your MCP client (like Claude Desktop) to connect to the mcpcap server:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpcap\": {\n      \"command\": \"mcpcap\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### 3. Analyze PCAP Files\n\nUse the analysis tools with any PCAP file:\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## 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## 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## Configuration Options\n\n### Module Selection\n\n```bash\n# Load specific modules\nmcpcap --modules dns              # DNS analysis only\nmcpcap --modules dhcp             # DHCP analysis only\nmcpcap --modules icmp             # ICMP analysis only  \nmcpcap --modules dns,dhcp,icmp    # 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### Complete Configuration Example\n\n```bash\nmcpcap --modules dns,dhcp,icmp --max-packets 500\n```\n\n## CLI Reference\n\n```bash\nmcpcap [--modules MODULES] [--max-packets N]\n```\n\n**Options:**\n- `--modules MODULES`: Comma-separated modules to load (default: `dns,dhcp,icmp`)\n  - Available modules: `dns`, `dhcp`, `icmp`\n- `--max-packets N`: Maximum packets to analyze per file (default: unlimited)\n\n**Examples:**\n```bash\n# Start with all modules\nmcpcap\n\n# DNS analysis only\nmcpcap --modules dns\n\n# With packet limits for large files\nmcpcap --max-packets 1000\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- `icmp.pcap` - ICMP ping and traceroute traffic\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_icmp_packets(\"./examples/icmp.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, and ICMP analysis implementations  \n3. **MCP Interface**: Tool registration and prompt management\n4. **FastMCP Framework**: MCP server implementation\n\n### Tool Flow\n```\nMCP Client Request \u2192 analyze_*_packets(pcap_file)\n                  \u2192 BaseModule.analyze_packets()\n                  \u2192 Module._analyze_protocol_file()\n                  \u2192 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- TCP connection tracking  \n- BGP routing analysis\n- SSL/TLS certificate analysis\n- Network forensics tools\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://wiki.wireshark.org/uploads/dns.cap\")\nanalyze_dhcp_packets(\"https://example.com/network-capture.pcap\")\nanalyze_icmp_packets(\"https://example.com/ping-test.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, TCP, 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",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2025 danohn\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE.\n        ",
    "summary": "A modular Python MCP Server for analyzing PCAP files",
    "version": "0.5.10",
    "project_urls": {
        "Homepage": "https://mcpcap.ai",
        "Issues": "https://github.com/mcpcap/mcpcap/issues",
        "Repository": "https://github.com/mcpcap/mcpcap"
    },
    "split_keywords": [
        "pcap",
        " network",
        " analysis",
        " mcp",
        " dns"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "61dfe03ae445e4075520f0ebfe7561fecee5d4683049a1aac4425838d6d6f07c",
                "md5": "f001bf8acaeaa9fb03e1ba7b4878027c",
                "sha256": "133b67def92b23db1537be2a6d08e9c3405e23c87a0baa9fd48a8257a4a19fd3"
            },
            "downloads": -1,
            "filename": "mcpcap-0.5.10-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f001bf8acaeaa9fb03e1ba7b4878027c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 22776,
            "upload_time": "2025-09-12T05:10:49",
            "upload_time_iso_8601": "2025-09-12T05:10:49.179143Z",
            "url": "https://files.pythonhosted.org/packages/61/df/e03ae445e4075520f0ebfe7561fecee5d4683049a1aac4425838d6d6f07c/mcpcap-0.5.10-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "24cc70d3f86993c60279f00ef947779c7197b17eebc97967220cf8ddc44e2663",
                "md5": "f0719c33cd396abb10c8db38711f0042",
                "sha256": "3d74da4efc00d717b1ed5e61245cd3bd320122e1e2397d370e1f39f0a168ef6e"
            },
            "downloads": -1,
            "filename": "mcpcap-0.5.10.tar.gz",
            "has_sig": false,
            "md5_digest": "f0719c33cd396abb10c8db38711f0042",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 1604304,
            "upload_time": "2025-09-12T05:10:50",
            "upload_time_iso_8601": "2025-09-12T05:10:50.395263Z",
            "url": "https://files.pythonhosted.org/packages/24/cc/70d3f86993c60279f00ef947779c7197b17eebc97967220cf8ddc44e2663/mcpcap-0.5.10.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-12 05:10:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mcpcap",
    "github_project": "mcpcap",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mcpcap"
}