Skip to main content
Glama

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

Related MCP server: Wireshark-MCP

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 .

Available Tools

76 tools
capture_checkpointA

Persist and return metadata for a capture without stopping it.

Inputs: capture_id (required). Returns: object

capture_deleteB

Delete or mark a managed capture session after optionally stopping it.

Inputs: capture_id (required), delete_files, force_stop. Returns: object

capture_listA

List managed live or previous capture sessions and artifact summaries.

Inputs: no named parameters. Returns: object

capture_list_interfacesB

List live capture interfaces.

Inputs: no named parameters. Returns: object

capture_list_linktypesB

List link-layer types supported by an interface.

Inputs: interface (required). Returns: object

capture_ring_bufferC

Start a long ring-buffer capture using configured file count and size limits.

Inputs: interface, duration, capture_filter. Returns: object

capture_sampleC

Capture a short bounded sample to a pcapng artifact.

Inputs: interface, duration, packet_count, capture_filter. Returns: object

capture_startC

Start a bounded live capture. Long captures use ring-buffer rotation by default.

Inputs: interface, duration, packet_count, capture_filter, +1 more. Returns: object

capture_statusB

Return process and artifact status for a running or previous capture.

Inputs: capture_id (required). Returns: object

capture_stopC

Stop a managed capture.

Inputs: capture_id (required). Returns: object

capture_tail_summaryC

Summarize the newest pcapng file in a managed capture directory.

Inputs: capture_id (required), limit. Returns: object

decode_asC

Analyze a capture with a tshark decode-as rule.

Inputs: capture_path (required), rule (required), fields, limit. Returns: object

diagnostics_check_installA

Report detected Wireshark binaries and versions.

Inputs: no named parameters. Returns: object

diagnostics_supported_featuresA

Return registry counts that summarize local Wireshark dissection support.

Inputs: no named parameters. Returns: object

file_infoA

Return capinfos metadata for a capture file.

Inputs: capture_path (required). Returns: object

file_typeC

Return capture file type.

Inputs: capture_path (required). Returns: object

file_verify_readableB

Verify that tshark can read at least one packet from a capture.

Inputs: capture_path (required). Returns: object

filter_validateC

Validate a display filter against a capture.

Inputs: capture_path (required), display_filter (required). Returns: object

generate_from_hexdumpC

Generate a capture from a text hex dump.

Inputs: hexdump_text (required), output_path (required), encapsulation, file_format. Returns: object

generate_random_captureC

Generate a local random or malformed packet capture with randpkt.

Inputs: output_path (required), packet_type, count, max_bytes, +1 more. Returns: object

heuristic_enable_disableC

Analyze with selected heuristic dissectors enabled or disabled.

Inputs: capture_path (required), enable, disable, limit. Returns: object

llm_capture_briefC

Return a compact capture brief with metadata, top protocols, talkers, and notable packets.

Inputs: capture_path (required), limit. Returns: object

llm_dns_summaryC

Return DNS query, answer, and response-code summary for LLM triage.

Inputs: capture_path (required), limit. Returns: object

llm_follow_stream_hintC

Rank TCP streams worth following based on packet counts and examples.

Inputs: capture_path (required), limit. Returns: object

llm_http_summaryB

Return HTTP host, method, status, error, and slow-response summary.

Inputs: capture_path (required), limit, slow_seconds. Returns: object

llm_investigateC

Run a compact investigation recipe set and return next-tool hints.

Inputs: capture_path (required), focus, limit. Returns: object

llm_investigate_allC

Run inventory and bounded summaries for the top observed protocols.

Inputs: capture_path (required), limit, max_protocols. Returns: object

llm_ioc_candidatesC

Return candidate IPs, domains, HTTP hosts, URIs, user agents, and TLS SNI values.

Inputs: capture_path (required), limit. Returns: object

llm_profile_catalogB

Return curated protocol analysis profiles and fallback behavior.

Inputs: no named parameters. Returns: object

llm_protocol_findingsC

Return notable protocol findings such as resets, retransmissions, failures, and alerts.

Inputs: capture_path (required), limit. Returns: object

llm_protocol_inventoryC

Inventory observed protocols, expert rows, suggested filters, and next tools.

Inputs: capture_path (required), limit. Returns: object

llm_protocol_summaryC

Summarize one protocol using curated fields or Wireshark registry discovery.

Inputs: capture_path (required), protocol (required), limit. Returns: object

llm_tcp_healthC

Return TCP stream health markers such as retransmissions, resets, and zero-window events.

Inputs: capture_path (required), limit. Returns: object

llm_timelineC

Return a protocol-count timeline using bounded packet summaries.

Inputs: capture_path (required), bucket_seconds, limit. Returns: object

llm_tls_summaryC

Return TLS SNI, handshake type, and alert summary.

Inputs: capture_path (required), limit. Returns: object

llm_top_talkersC

Return ranked source-to-destination talkers from a bounded packet sample.

Inputs: capture_path (required), limit. Returns: object

open_in_wiresharkC

Open a capture in the Wireshark GUI.

Inputs: capture_path (required), display_filter, profile. Returns: object

packets_fieldsC

Extract selected tshark display fields.

Inputs: capture_path (required), fields (required), display_filter, limit. Returns: object

packets_filterC

Apply a display filter and return matching summaries.

Inputs: capture_path (required), display_filter (required), limit. Returns: object

packets_hexdumpC

Return packet hexdumps for bounded packets.

Inputs: capture_path (required), display_filter, limit. Returns: object

packets_jsonC

Return bounded tshark JSON packet output.

Inputs: capture_path (required), display_filter, limit. Returns: object

packets_rangeC

Return packet summaries for a frame range.

Inputs: capture_path (required), start_frame (required), end_frame (required), limit. Returns: object

packets_summaryC

Return LLM-sized packet list rows.

Inputs: capture_path (required), display_filter, limit. Returns: object

profile_analyzeC

Analyze with a Wireshark configuration profile.

Inputs: capture_path (required), profile (required), limit. Returns: object

protocol_enable_disableD

Analyze with selected protocols enabled or disabled.

Inputs: capture_path (required), enable, disable, limit. Returns: object

rawshark_fieldsC

Run rawshark over raw pcap records with explicit encapsulation and fields.

Inputs: raw_path (required), encapsulation (required), fields (required), display_filter. Returns: object

registry_dissector_tablesC

Search dissector tables.

Inputs: search, limit. Returns: object

registry_field_detailC

Return registry lines matching a field abbreviation.

Inputs: field (required). Returns: object

registry_fieldsC

Search the local Wireshark display field registry.

Inputs: search, limit. Returns: object

registry_output_formatsC

List capture output formats for a Wireshark utility.

Inputs: tool (required). Returns: object

registry_preferencesC

Search current Wireshark preferences.

Inputs: search, limit. Returns: object

registry_protocolsC

Search the local Wireshark protocol registry.

Inputs: search, limit. Returns: object

registry_tapsA

List tshark statistics taps.

Inputs: no named parameters. Returns: object

sharkd_closeC

Close a managed sharkd session.

Inputs: session_id (required), timeout. Returns: object

sharkd_followC

Follow a stream in sharkd using a protocol name and display filter.

Inputs: session_id (required), protocol (required), display_filter (required), timeout. Returns: object

sharkd_frameC

Return sharkd details for one frame, optionally with protocol tree and bytes.

Inputs: session_id (required), frame_number (required), protocol_tree, columns, +2 more. Returns: object

sharkd_framesA

Return sharkd packet-list frames for a bounded range or display filter.

Inputs: session_id (required), display_filter, skip, limit, +2 more. Returns: object

sharkd_openC

Open a capture in a local console-mode sharkd session.

Inputs: capture_path (required), profile, timeout. Returns: object

sharkd_requestC

Send a bounded generic JSON-RPC request to a managed sharkd session.

Inputs: session_id (required), method (required), params, timeout. Returns: object

sharkd_sessionsB

List managed sharkd sessions.

Inputs: no named parameters. Returns: object

sharkd_statusC

Get sharkd status for a loaded capture.

Inputs: session_id (required), timeout. Returns: object

stats_conversationsC

Return conversation statistics for a protocol.

Inputs: capture_path (required), protocol. Returns: object

stats_dnsC

Return DNS query/response fields.

Inputs: capture_path (required), limit. Returns: object

stats_endpointsC

Return endpoint statistics for a protocol.

Inputs: capture_path (required), protocol. Returns: object

stats_expertC

Return Wireshark expert information.

Inputs: capture_path (required). Returns: object

stats_httpC

Return HTTP request/response fields.

Inputs: capture_path (required), limit. Returns: object

stats_ioC

Return IO statistics.

Inputs: capture_path (required), interval. Returns: object

stats_protocol_hierarchyC

Return protocol hierarchy statistics.

Inputs: capture_path (required). Returns: object

stats_tcpC

Return notable TCP stream fields.

Inputs: capture_path (required), limit. Returns: object

stats_tlsC

Return TLS handshake and SNI-oriented fields.

Inputs: capture_path (required), limit. Returns: object

transform_convert_formatC

Convert capture file format.

Inputs: input_path (required), output_path (required), file_format (required). Returns: object

transform_deduplicateC

Remove duplicate packets with editcap.

Inputs: input_path (required), output_path (required), duplicate_window. Returns: object

transform_mergeC

Merge multiple capture files.

Inputs: input_paths (required), output_path (required), append. Returns: object

transform_reorderC

Reorder a capture by timestamp.

Inputs: input_path (required), output_path (required), skip_if_ordered. Returns: object

transform_trimC

Trim a capture by time or packet range.

Inputs: input_path (required), output_path (required), start_time, end_time, +1 more. Returns: object

wireshark_cliD

Expert escape hatch for allowlisted Wireshark binaries only.

Inputs: tool (required), args (required), timeout. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 76 tools

    Disambiguation4/5

    Tools are grouped with clear prefixes (capture_, stats_, llm_, etc.), and within each group, actions are distinct. Some overlap exists between llm summary tools and stats tools, but descriptions differentiate them sufficiently.

    Naming Consistency5/5

    All tools use consistent snake_case naming with informative prefixes, making the function clear. The pattern is uniform across all 76 tools.

    Tool Count2/5

    76 tools is excessive for most use cases, even considering the breadth of Wireshark. The sheer number can overwhelm LLM context windows and cause selection errors, scoring poorly against the calibration where 25+ is considered too many.

    Completeness5/5

    The tool set covers nearly every aspect of capture management, file operations, packet analysis, statistics, transformations, and LLM-oriented summaries. It includes advanced features like sharkd sessions and heuristic dissection, leaving few obvious gaps.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers