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:

/Applications/Wireshark.app/Contents/MacOS

Install

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:

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:

wireshark-mcp --print-config

To remove the registration:

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.

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:

{
  "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:

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:

capture_list_interfaces -> capture_ring_buffer -> capture_tail_summary -> llm_protocol_inventory

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

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:

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:

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