mcp-pcap

A Model Context Protocol (MCP) server for PCAP files.

This server allows AI to parse pcap (.pcap) files to help Ops to debug or trouble-shooting network issues. Also, it could be used to achieve agentic work flows.

How To Use

The following configuration block should be applicable for most clients that support MCP today (Claude Code, Claude Desktop, etc):

"mcp-pcap": {
  "command": "/PATH_TO_BIN/mcp-pcap",
    "args": [],
    "env": {}
}

The server runs on stdio mode and doesn't need any additional parameters. It's strongly recommended to use local models (Ollama, LM Studio, etc) + agents for analyzing big pcap files. It's more efficient.

Resource Limits

When working with PCAP files, be aware of the following resource considerations:

• Recommended max file size: 500MB for optimal performance
• Memory usage: Approximately 2-3x the file size during processing (all packets are loaded into memory)
• Large files: For PCAP files larger than 500MB, use BPF filters to reduce the number of packets processed
• Example filter usage: tcp port 443 or host 192.168.1.1 to limit packet analysis

Note: Processing very large PCAP files without filtering may result in high memory usage or out-of-memory errors.

Available Tools

This tool is designed to help our Ops teams to solve daily operation issues. The following essential tools help us to trace down customer issues much more efficiently. More tools are on the way!

Tool Name	Description	Parameters	Returns
pcap_get_total_packet_count_from_file	Count the total packets of the given pcap file	filePath (string): Path to pcap file	Total packet count
pcap_get_packets	Get all packets from the given pcap file	filePath (string): Path to pcap file filter (string, optional): BPF filter	JSON array of packets with details including ID, protocol, source/destination IP and port, IP flags, and TCP flags
pcap_detect_malformed	Detect and analyze malformed packets in the given pcap file	filePath (string): Path to pcap file filter (string, optional): BPF filter	JSON array of malformed packets with error details, including packet ID, protocol, source/destination IP, error layers, error messages, and truncation status
pcap_detect_retransmits	Detect TCP retransmissions in the given pcap file	filePath (string): Path to pcap file filter (string, optional): BPF filter	JSON array of TCP retransmissions with details including packet ID, source/destination IP and port, sequence number, payload length, original packet ID, and TCP flags

BUILD

You will need Golang (we use v1.25) to build by:

$ make build

The following targets are also supported:

• make fmt - Do gofmt
• make vendor - Shortcut command to do go mod tidy and go mod vendor
• make superclean - Remove all files not part of the repo (including new files)

Since the C dependency of the google/gopacket, the compile will need CGO_ENABLED. On Linux, you will need to have libpcap-dev installed.

Acknowledgements

This server is built with MCP go-sdk and the excellent pcap library from google/gopacket, Also thanks for dreadl0ck/gopcap for a comprehensive comparison among different libraries.

License

This project is licensed under the MIT License - see the LICENSE file for details.