ai.mcpcap/mcpcap

Install

Config snippet generator goes here (5 client tabs)

README

# mcpcap

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

<p align="center">
  <img src="https://raw.githubusercontent.com/mcpcap/mcpcap/main/readme-assets/mcpcap-logo.png" alt="mcpcap logo" width="240" />
</p>

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, SIP, 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

```bash
pip install mcpcap
```

### Using uv

```bash
uv add mcpcap
```

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

```bash
uvx mcpcap
```

### Using Docker

Build the image from the repository root:

```bash
docker build -t mcpcap .
```

Run it over HTTP for MCP clients that connect to a network endpoint:

```bash
docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080
```

Run it over stdio for clients that can spawn `docker run` directly:

```bash
docker run --rm -i \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap
```

When you mount local captures into the container, use the container path in tool calls:

```text
analyze_dns_packets("/pcaps/dns.pcap")
```

Remote `http://` and `https://` PCAP URLs work without a volume mount because mcpcap downloads them inside the container at call time.

### Using Docker Compose

For the default HTTP workflow, start the bundled Compose service:

```bash
docker compose up
```

This pulls `ghcr.io/mcpcap/mcpcap:latest`, publishes `http://127.0.0.1:8080/mcp`, and mounts `./examples` into the container as `/pcaps`.

```text
analyze_dns_packets("/pcaps/dns.pcap")
```

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

For local development against the checked-out source instead of GHCR:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
```

## Quick Start

### 1. Start the MCP Server

Start mcpcap as a stateless MCP server:

```bash
# Default stdio transport for Claude Desktop and similar clients
mcpcap

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

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

# Start an HTTP transport server for remote MCP clients
mcpcap --transport http --host 127.0.0.1 --port 8080
```

### 2. Connect Your MCP Client

Use stdio transport for local MCP clients like Claude Desktop:

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

Use HTTP transport when your MCP client expects a network endpoint:

```bash
mcpcap --transport http --host 127.0.0.1 --port 8080
```

Point your HTTP-capable MCP client at:

```text
http://127.0.0.1:8080/mcp
```

Docker users can publish the same endpoint with:

```bash
docker run --rm \
  -p 8080:8080 \
  -v "/path/to/captures:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080
```

Or with Compose:

```bash
docker compose up
```

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