Wireshark MCP
Provides tools for live capture, pcap analysis, file transforms, Wireshark registries, local sharkd sessions, and LLM-oriented summaries, enabling programmatic network traffic capture and analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Wireshark MCP capture and summarize traffic on en0 for 30 seconds"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/MacOSRelated MCP server: Wireshark-MCP
Install
pipx install git+https://github.com/andsopwn/wireshark-mcp.git
wireshark-mcp --installIf 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 --installwireshark-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-configTo remove the registration:
wireshark-mcp --uninstallCodex 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 --> CodexThe code is intentionally split by responsibility:
server.pypublishes MCP tools and keeps tool handlers thin.dumpcap.pyandcaptures.pyhandle live capture, ring buffers, metadata, process recovery, and cleanup.tshark.pywraps packet reads, field extraction, display filters, registries, and statistics.files.pywraps file-level tools such ascapinfos,editcap,mergecap,text2pcap, andrandpkt.sharkd.pymanages local console-modesharkdsessions for interactive frame and stream inspection.llm.pyandprotocols.pyturn 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_featuresLive capture:
capture_list_interfaces,capture_sample,capture_start,capture_ring_buffer,capture_list,capture_status,capture_checkpoint,capture_stop,capture_delete,capture_tail_summaryFile metadata:
file_info,file_type,file_verify_readablePacket analysis:
packets_summary,packets_json,packets_fields,packets_filter,packets_range,packets_hexdump,filter_validateStatistics:
stats_protocol_hierarchy,stats_conversations,stats_endpoints,stats_io,stats_expert,stats_http,stats_dns,stats_tls,stats_tcpRegistries:
registry_protocols,registry_fields,registry_field_detail,registry_preferences,registry_dissector_tables,registry_taps,registry_output_formatsTransforms:
transform_trim,transform_deduplicate,transform_merge,transform_reorder,transform_convert_formatGeneration:
generate_from_hexdump,generate_random_capturesharkd:
sharkd_open,sharkd_sessions,sharkd_request,sharkd_status,sharkd_frames,sharkd_frame,sharkd_follow,sharkd_closeLLM 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_catalogGUI 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_closeUse 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 responsesllm_http_summary: hosts, methods, status classes, 4xx/5xx, slow responsesllm_tls_summary: SNI, handshake types, TLS alertsllm_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_inventoryFor a pcap you already have, start with protocol discovery:
file_info -> llm_protocol_inventory -> llm_protocol_summary -> packets_filterFor 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_closeFor 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_WORKDIRWIRESHARK_MCP_BIN_DIRWIRESHARK_MCP_TSHARK,WIRESHARK_MCP_DUMPCAP, etc.WIRESHARK_MCP_DEFAULT_INTERFACEWIRESHARK_MCP_MAX_CAPTURE_SECONDSWIRESHARK_MCP_LONG_CAPTURE_SECONDSWIRESHARK_MCP_RING_FILE_SIZE_MIBWIRESHARK_MCP_RING_FILE_COUNTWIRESHARK_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 toolscapture_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
Scored across 76 tools
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.
All tools use consistent snake_case naming with informative prefixes, making the function clear. The pattern is uniform across all 76 tools.
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.
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
Related MCP Connectors
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
LLM Orchestration Observability Agent
LLM Observability & Orchestration Agent (LangChain Community)
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to analyze, filter, and capture network traffic using Wireshark/tshark, allowing natural language interaction with packet captures.14212 PyPI69MIT
- AlicenseCqualityDmaintenanceEnables LLMs to perform automated network forensics, threat hunting, and traffic analysis using Wireshark/TShark.344MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with tshark and related command-line tools for live packet capture, PCAP analysis, filtering, stream following, and capture file merging.1MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to securely investigate packet captures through Wireshark's tshark engine, with bounded tools for protocol inventory, TCP failure diagnosis, latency measurement, and threat hunting.12MIT