# Wireshark MCP

Local stdio MCP server for Wireshark CLI workflows.

It exposes live capture, long-running ring-buffer capture, pcap analysis, file transforms, Wireshark registries, local `sharkd` sessions, and LLM-oriented summaries through tools that Codex and other MCP clients can call.

The intent is not to replace Wireshark. The server gives an LLM a disciplined way to capture traffic, reduce large pcaps into bounded evidence, and then jump into exact packets or streams when the summary points somewhere interesting.

## Requirements

- Python 3.11+
- Wireshark with command-line tools installed
- Codex CLI or another MCP client

On macOS, the server automatically falls back to:

```text
/Applications/Wireshark.app/Contents/MacOS
```

## Install

```bash
pipx install git+https://github.com/andsopwn/wireshark-mcp.git
wireshark-mcp --install
```

If you do not use `pipx`, install it into your user Python environment:

```bash
python3.11 -m pip install --user git+https://github.com/andsopwn/wireshark-mcp.git
wireshark-mcp --install
```

`wireshark-mcp --install` registers the command with Codex as the `wireshark` MCP server. To see what will be registered before changing Codex config:

```bash
wireshark-mcp --print-config
```

To remove the registration:

```bash
wireshark-mcp --uninstall
```

Codex and the IDE extension share the same MCP configuration. In a Codex TUI, use `/mcp` to see active MCP servers.

## Architecture

The server is a local stdio MCP process. It does not listen on a network port. Codex starts it when the MCP server is enabled, sends tool calls over stdio, and receives JSON-sized results back.

```mermaid
flowchart LR
    Codex["Codex / MCP client"]
    Server["wireshark-mcp<br/>FastMCP stdio server"]
    Capture["dumpcap<br/>live and ring capture"]
    Tshark["tshark<br/>fields, stats, registries"]
    Files["capinfos / editcap / mergecap<br/>file utilities"]
    Sharkd["sharkd<br/>interactive sessions"]
    Artifacts[("pcapng artifacts")]
    Summaries["LLM summaries<br/>protocol inventory and recipes"]
    Detail["frame and stream detail"]

    Codex -- "stdio MCP" --> Server
    Server --> Capture
    Server --> Tshark
    Server --> Files
    Server --> Sharkd
    Capture --> Artifacts
    Files --> Artifacts
    Artifacts --> Tshark
    Artifacts --> Sharkd
    Tshark --> Summaries
    Sharkd --> Detail
    Summaries --> Codex
    Detail --> Codex
```

The code is intentionally split by responsibility:

- `server.py` publishes MCP tools and keeps tool handlers thin.
- `dumpcap.py` and `captures.py` handle live capture, ring buffers, metadata, process recovery, and cleanup.
- `tshark.py` wraps packet reads, field extraction, display filters, registries, and statistics.
- `files.py` wraps file-level tools such as `capinfos`, `editcap`, `mergecap`, `text2pcap`, and `randpkt`.
- `sharkd.py` manages local console-mode `sharkd` sessions for interactive frame and stream inspection.
- `llm.py` and `protocols.py` turn raw Wireshark output into smaller summaries that are easier for an LLM to reason over.

The usual data flow is capture or load a pcap, build a compact inventory, inspect the interesting protocols, then drill into exact frames only when needed. This keeps long captures usable without dumping thousands of packets into the model context.

## Tool Groups

- Diagnostics: `diagnostics_check_install`, `diagnostics_supported_features`
- Live capture: `capture_list_interfaces`, `capture_sample`, `capture_start`, `capture_ring_buffer`, `capture_list`, `capture_status`, `capture_checkpoint`, `capture_stop`, `capture_delete`, `capture_tail_summary`
- File metadata: `file_info`, `file_type`, `file_verify_readable`
- Packet analysis: `packets_summary`, `packets_json`, `packets_fields`, `packets_filter`, `packets_range`, `packets_hexdump`, `filter_validate`
- Statistics: `stats_protocol_hierarchy`, `stats_conversations`, `stats_endpoints`, `stats_io`, `stats_expert`, `stats_http`, `stats_dns`, `stats_tls`, `stats_tcp`
- Registries: `registry_protocols`, `registry_fields`, `registry_field_detail`, `registry_preferences`, `registry_dissector_tables`, `registry_taps`, `registry_output_formats`
- Transforms: `transform_trim`, `transform_deduplicate`, `transform_merge`, `transform_reorder`, `transform_convert_format`
- Generation: `generate_from_hexdump`, `generate_random_capture`
- sharkd: `sharkd_open`, `sharkd_sessions`, `sharkd_request`, `sharkd_status`, `sharkd_frames`, `sharkd_frame`, `sharkd_follow`, `sharkd_close`
- LLM summaries: `llm_capture_brief`, `llm_top_talkers`, `llm_protocol_findings`, `llm_timeline`, `llm_ioc_candidates`, `llm_follow_stream_hint`, `llm_dns_summary`, `llm_http_summary`, `llm_tls_summary`, `llm_tcp_health`, `llm_investigate`, `llm_protocol_inventory`, `llm_protocol_summary`, `llm_investigate_all`, `llm_profile_catalog`
- GUI and expert mode: `open_in_wireshark`, `wireshark_cli`

## Long Capture

Live capture is enabled by default. If a capture lasts longer than 10 minutes, the server uses `dumpcap` ring-buffer rotation unless `single_file` is set.

Default long-capture settings:

- Max explicit capture duration: 8 hours
- Ring file size: 64 MiB
- Ring file count: 512

Example MCP call shape:

```json
{
  "interface": "en0",
  "duration": 28800,
  "capture_filter": "not port 22"
}
```

Use `capture_checkpoint` and `capture_tail_summary` during long captures so the LLM inspects only recent files or bounded packet windows.

The capture manager writes metadata under `captures/<capture_id>/metadata.json`. After an MCP server restart, `capture_list`, `capture_status`, and `capture_stop` can reconcile previous sessions from that metadata and, when the recorded `dumpcap` PID is still alive, stop the recovered process. `capture_delete` refuses to remove a running capture unless `force_stop` is set.

## sharkd Sessions

`sharkd` is run in console mode through stdio. The server does not open a public socket.

Typical workflow:

```text
sharkd_open -> sharkd_status -> sharkd_frames -> sharkd_frame -> sharkd_close
```

Use `sharkd_request` for less common JSON-RPC methods such as `analyse`, `intervals`, `tap`, `follow`, `check`, `complete`, or `info`. Large responses such as stream follows and export-object downloads should stay bounded by a precise display filter.

## LLM Recipes

Use `llm_investigate` for a focused first pass over common DNS, HTTP, TLS, TCP, and IOC surfaces. Use `llm_investigate_all` when you do not know what protocols matter yet. It starts with an inventory, picks the top observed protocols, and returns bounded summaries for each one.

Focused recipes:

- `llm_dns_summary`: query names, response codes, answers, failed responses
- `llm_http_summary`: hosts, methods, status classes, 4xx/5xx, slow responses
- `llm_tls_summary`: SNI, handshake types, TLS alerts
- `llm_tcp_health`: retransmissions, out-of-order, lost segment, duplicate ACK, zero-window, window-full, reset markers

Broad protocol analysis:

- `llm_protocol_inventory`: counts observed protocols, collects Wireshark expert rows, and suggests display filters.
- `llm_protocol_summary`: summarizes one protocol using curated fields when available. If the protocol is not curated, it discovers useful fields from the local Wireshark registry.
- `llm_investigate_all`: inventories the capture and summarizes the top protocols without returning raw packet JSON.
- `llm_profile_catalog`: shows the curated protocol families and the generic fallback behavior.

Curated coverage includes core IP traffic, DNS-family name resolution, DHCP/BOOTP, HTTP/HTTP2/HTTP3, QUIC, TLS, Kerberos, LDAP, NTLMSSP, SMB/SMB2, RDP, SMTP, IMAP, POP, FTP, TFTP, MySQL, PostgreSQL, SSH, NTP, SNMP, Syslog, SIP, RTP, and RTCP. Anything outside that list still gets a best-effort summary through `tshark -G fields`.

The new broad-analysis tools use a stable result shape: `ok`, `schema_version`, `scope`, `sample_size`, protocol or field counters, findings, evidence rows, suggested filters, next tools, and errors. That consistency matters when Codex chains tool calls across an investigation.

## Practical Workflows

For a live issue, start narrow:

```text
capture_list_interfaces -> capture_ring_buffer -> capture_tail_summary -> llm_protocol_inventory
```

For a pcap you already have, start with protocol discovery:

```text
file_info -> llm_protocol_inventory -> llm_protocol_summary -> packets_filter
```

For a deeper packet-level pass, open a `sharkd` session after the summary points to a protocol, frame, or stream:

```text
llm_follow_stream_hint -> sharkd_open -> sharkd_frames -> sharkd_frame -> sharkd_follow -> sharkd_close
```

For incident-style triage, use `llm_investigate_all` first, then ask for a specific protocol summary. This usually gives better results than starting with raw packet JSON.

## Environment Variables

- `WIRESHARK_MCP_WORKDIR`
- `WIRESHARK_MCP_BIN_DIR`
- `WIRESHARK_MCP_TSHARK`, `WIRESHARK_MCP_DUMPCAP`, etc.
- `WIRESHARK_MCP_DEFAULT_INTERFACE`
- `WIRESHARK_MCP_MAX_CAPTURE_SECONDS`
- `WIRESHARK_MCP_LONG_CAPTURE_SECONDS`
- `WIRESHARK_MCP_RING_FILE_SIZE_MIB`
- `WIRESHARK_MCP_RING_FILE_COUNT`
- `WIRESHARK_MCP_MAX_OUTPUT_BYTES`

## Local Development

For local edits, use an editable install:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```