dsct MCP server
Commit Nov 15, 2026Enables AI agents to dissect packet captures and analyze network traffic using machine-readable JSONL and SQL queries.
Also known as higebu/dsct
- Stars
- 0
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is dsct MCP?
dsct enables AI agents to dissect packet captures and analyze network traffic using machine-readable JSONL and SQL queries. It exposes 9 tools, such as dsct_read_packets, dsct_get_stats, dsct_list_protocols.
Summary generated from the project's README
About dsct MCP server
Analyzing network traffic and dissecting packet captures is what dsct enables for developers using AI agents. This MCP server allows large language models to interact directly with pcap and pcapng files through a standardized interface. By running the server over stdio, agents can access specialized tools like dsct_read_packets and dsct_get_stats to inspect protocol layers and timing without manual command line intervention.
Users can perform complex investigations using SQL syntax to query a SQLite index built from the capture data. The server is designed for efficiency, providing machine-readable JSONL output and predictable memory usage even when handling massive files. It supports advanced features such as ESP decryption via esp_sa parameters and multi-threaded dissection to speed up filter evaluation. Whether you are using Claude Code, GitHub Copilot CLI, or Gemini, this tool provides the structured data necessary for automated network forensics and protocol analysis.
What you can do with it
- 1Extract specific protocol packetsAn AI agent can retrieve a limited number of DNS query packets from a large capture file using a filter.
- 2Perform statistical network analysisA developer can ask an agent to summarize the protocol distribution and packet counts within a capture.
- 3Query captures with SQLYou can use SQL to find specific TCP segments or filter packets based on complex criteria like max depth.
- 4Discover protocol capabilitiesAn agent can list all supported protocols and their associated layers to understand what data is available for dissection.
Written from the project's README. Every use case is checked against a quote from it.
dsct MCP tools 9
Detected from the READMEdsct_read_packetsdsct_get_statsdsct_list_protocolsdsct_list_fieldsdsct_get_schemadsct_query_sqllayersfieldsschema
| dsct_read_packets | — | |
| dsct_get_stats | — | |
| dsct_list_protocols | — | |
| dsct_list_fields | — | |
| dsct_get_schema | — | |
| dsct_query_sql | — | |
| layers | — | |
| fields | — | |
| schema | — |
Configuration
DSCT_THREADS
| Name | Description | |
|---|---|---|
| DSCT_THREADS | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehigebu/dsct is public and reachablegithub.com/higebu/dsct ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/higebu/dsct ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdsct
dsct is a packet dissector CLI for LLMs and large captures.
It is built around two ideas:
- machine-readable output by default
- predictable memory use on big
pcap/pcapngfiles
dsct read streams packet records as JSONL, dsct stats scans captures in a single pass, and the optional TUI opens large files with memory mapping and on-demand dissection instead of decoding the whole capture up front.
Why dsct
LLM-friendly by default
dsct reademits JSONL packet recordsdsct stats,dsct list,dsct fields,dsct version, anddsct schemaemit JSON- errors, warnings, and progress updates are structured JSON on stderr
- capabilities and schemas can be discovered from the CLI itself
Works well on large captures
readandstatsprocess captures one packet at a time- stdin is supported, so
tcpdump -w - | dsct ...works naturally - no human-oriented table parsing is required before automation can start
MCP server built in
dsct mcp starts a Model Context Protocol server over stdio. AI agents can call tools like dsct_read_packets and dsct_get_stats directly, without shelling out to the CLI.
Low-memory TUI for large files
The optional TUI is designed for large captures too:
- capture files are opened with memory-mapped I/O
- indexing starts from packet headers instead of fully decoding every packet
- packet list rows are dissected on demand for visible rows
- the selected packet is decoded in detail only when needed
- the hex view reads directly from the mapped file
The packet list and detail pane show every packet exactly as dsct read
dissects it, whatever order you view packets in. A packet whose
dissection depends on earlier packets — TCP stream tracking and reassembly
(tcp.stream_id, HTTP, TLS, ...), HTTP/2 HPACK, NetFlow v9 / IPFIX
templates, or IP fragment reassembly — is taken from a background pass that
dissects the capture once in capture order. Until that pass reaches such a
packet, its row and detail show Dissecting packets in capture order....
The pass keeps those results in a temporary file under
$XDG_CACHE_HOME/dsct (or ~/.cache/dsct, falling back to the system temp
directory) that is removed on exit: about 200 bytes for a plain TCP
segment, plus the reassembled data for a packet that completes a
reassembly. In memory it keeps 8 bytes per packet. If the pass fails
(for example, the disk is full), the TUI reports it and dissects the
remaining packets on demand. Follow Stream scans the capture in order
with a fresh registry, so it finds the stream ID shown in the detail pane;
:stats dissects the displayed packets in order with a fresh registry, so
its result does not depend on what was viewed before.
Installation
CLI only:
cargo install dsct
With the optional TUI:
cargo install dsct --features tui
brew install higebu/tap/dsct
AI coding agent plugins
Install as a plugin via the marketplace to get the MCP server and the
analyze-packets skill automatically:
Claude Code
claude plugin marketplace add higebu/dsct
claude plugin install dsct@dsct
GitHub Copilot CLI
copilot plugin marketplace add higebu/dsct
copilot plugin install dsct@dsct
OpenAI Codex CLI
Add the MCP server, then install the analyze-packets skill inside Codex:
codex mcp add dsct -- dsct mcp
$skill-installer higebu/dsct skills/analyze-packets
Gemini CLI
gemini extensions install https://github.com/higebu/dsct
Quick start
Get a capture overview:
dsct stats capture.pcap
Read packets as JSONL:
dsct read capture.pcap
By default, dsct read outputs at most 1 000 packets. Use --count to
change the limit or --no-limit to remove it:
dsct read capture.pcap --count 50
dsct read capture.pcap --no-limit
Filter packets:
dsct read capture.pcap -f dns --count 10
dsct read capture.pcap -f "dns AND dns.qr = 'Query'"
Filter expressions use SQL syntax with AND, OR, NOT, parentheses, and
comparison operators (=, !=, >, <, >=, <=):
dsct read capture.pcap -f "dns OR (tcp AND ipv4.src = '10.0.0.1')"
dsct read capture.pcap -f "tcp.dst_port > 1024 AND NOT dns"
Nested fields are addressed with dots (dns.questions.name); the leading
segment matches the top-level field and any nested container of that name, so
bgp.nlri.route_type reaches MP_REACH NLRI.
Sample evenly across the capture:
dsct read capture.pcap --sample-rate 100
dsct read capture.pcap -f dns --sample-rate 10 --count 50
Read from a pipe:
tcpdump -w - -c 1000 | dsct read -
tcpdump -w - -i eth0 udp port 53 | dsct read - -f dns
Include the original packet bytes (link-layer included) as a hex string under
raw_bytes for downstream parsing or reconstruction:
dsct read capture.pcap --raw-bytes --count 1
Decrypt ESP with --esp-sa (repeatable; also accepted by index and
sql). The key is the full KEYMAT — cipher key followed by the salt or
nonce — and dsct read --help lists the algorithms:
dsct read esp.pcap --esp-sa 0x1001:aes-128-gcm:0x000102030405060708090a0b0c0d0e0fcafebabe
dsct read esp.pcap --esp-sa 0x1001:aes-128-cbc:0x<16-byte key>:hmac-sha1-96:0x<20-byte key>
When the SA uses Extended Sequence Numbers (the IKEv2 default), append :esn
(high-order 32 bits 0) or :esn=HIGH (decimal or 0x hex). Only the
low-order 32 bits are on the wire (RFC 4303 §2.2.1) and GCM, CCM and
ChaCha20-Poly1305 include the high-order bits in their AAD (RFC 4106 §5), so
such an SA without :esn fails to decrypt. esn is rejected for the other
algorithms, which do not use it. HIGH is fixed per SA, so packets sent after
the low-order 32 bits wrap within the capture do not decrypt:
dsct read esp.pcap --esp-sa 0x1001:aes-128-gcm:0x000102030405060708090a0b0c0d0e0fcafebabe:esn
dsct read esp.pcap --esp-sa 0x1001:aes-128-gcm:0x000102030405060708090a0b0c0d0e0fcafebabe:esn=1
The MCP esp_sa parameter takes the same strings.
Speed up filter evaluation on large files with --threads:
dsct read capture.pcap -f "icmp" --no-limit --threads 4
DSCT_THREADS=4 dsct read capture.pcap -f "arp" --no-limit
--threads distributes dissection and filter evaluation across N worker
threads for file input with a --filter (except filters on packet numbers
only, and runs with --esp-sa, which stay sequential). Dissection is
optimistic: a packet whose dissection does not touch state kept across
packets keeps its parallel result, and a packet whose dissection does — TCP
stream tracking and reassembly (tcp.stream_id, HTTP, TLS, ...), HTTP/2
HPACK, NetFlow v9 / IPFIX templates, or IP fragment reassembly — is
dissected again in capture order on the main thread. The output is always
identical to --threads 1. Captures without such packets (ICMP, ARP, plain
UDP such as DNS, ...) run fully in parallel; the more stateful packets a
capture has, the smaller the speed-up, down to roughly sequential speed for
an all-TCP capture. Stdin input always uses the sequential path.
IPv4 and IPv6 fragments are reassembled: the fragment that completes a datagram carries the reassembled upper layers.
Query a capture with SQL (the SQLite index is built on first use and reused afterwards):
dsct sql capture.pcap "SELECT number, stack FROM packets WHERE max_depth > 0 LIMIT 10"
dsct sql capture.pcap "SELECT * FROM tcp_segments WHERE flow_id = 0 ORDER BY packet_number"
dsct sql capture.pcap --schema
See SQL queries for the database layout.
Inspect available fields and schemas:
dsct fields dns
dsct schema read
Open the TUI for a large file (when built with --features tui):
dsct tui capture.pcap
In the TUI, press ? to open the built-in help overlay and q to quit.
Typical workflow
# 1. Discover supported protocols
dsct list
# 2. Inspect available filter fields
dsct fields dns
# 3. Read matching packets as JSONL
dsct read capture.pcap -f "dns AND dns.qr = 'Query'" --count 20
# 4. Get capture-wide statistics
dsct stats capture.pcap --top-talkers
Commands
| Command | What it does |
|---|---|
dsct read <FILE> |
Stream packet records as JSONL |
dsct stats <FILE> |
Emit capture statistics as JSON |
dsct index <FILE> |
Build (or refresh) the SQLite index used by dsct sql |
dsct sql <FILE> <QUERY> |
Run a read-only SQL query against the capture's SQLite index, rows as JSONL |
dsct list |
List supported protocols as JSON (name, full_name, layer, spec references) |
dsct fields [PROTOCOL...] |
List filterable fields as JSON |
dsct schema [COMMAND] |
Show JSON Schema for command output |
dsct version |
Show version and capability information as JSON |
dsct mcp |
Start an MCP server over stdio |
dsct tui <FILE> |
Open the interactive TUI for a capture file (tui feature only) |
Run --help on any command for the full option list.
MCP tools
dsct mcp exposes the following tools over the Model Context Protocol:
| Tool | Description |
|---|---|
dsct_read_packets |
Dissect packets from a pcap/pcapng capture file. Returns an array of dissected packet objects with protocol layers and fields. |
dsct_get_stats |
Get protocol statistics from a capture file. Returns packet counts, timing, protocol distribution, and optional deep analysis. |
dsct_list_protocols |
List all supported protocols (name, full_name, layer, and spec references with id/title/url). |
dsct_list_fields |
List available field names for protocols. qualified_name is the path to use in dsct_read_packets filter/fields. |
dsct_get_schema |
Get the JSON schema for command output formats (read, stats or sql). |
dsct_query_sql |
Run a read-only SQL query against the capture's SQLite index (built on first use). Returns result rows plus index status; schema: true returns the table layout. |
Protocol versions
The server speaks both protocol eras and picks one per request:
2026-07-28(stateless): declare the version on every request viaparams._meta(io.modelcontextprotocol/protocolVersionandio.modelcontextprotocol/clientCapabilitiesare required), and probe withserver/discover.pingis not served in this era.2025-11-25/2025-03-26/2024-11-05(legacy): negotiate via theinitializehandshake as before.
Key parameters
dsct_read_packets: file (required), filter, count, offset, packet_number, decode_as, esp_sa, verbose, layers, fields
layers: protocol names to keep in each packet'slayersarray ("BGP"or["IPv4", "TCP", "BGP"]);stackis unaffected.fields: qualified field paths to keep ("BGP.nlri","BGP.path_attributes.value.nlri.route_type"); protocols not listed keep their default fields. The last segment accepts thedefault_fields.tomlpatterns (prefix*,*suffix).
Both are MCP-only and useful for large protocols such as BGP.
dsct_query_sql: file (required), sql, schema, tables, count, db, no_build, decode_as, esp_sa
schema: truereturns a compact list of tables and views; addtables("tcp"or["tcp", "bgp"]) for full column detail.
Configuration example
Add dsct to your MCP client (e.g. Claude Desktop):
{
"mcpServers": {
"dsct": {
"command": "dsct",
"args": ["mcp"]
}
}
}
Default limits
When count is omitted, dsct_read_packets returns at most 1 000 packets
(configurable via DSCT_MCP_DEFAULT_COUNT). dsct_get_stats processes the
entire capture by default. All tool calls are subject to a per-execution
timeout; on timeout the server returns a JSON-RPC error and no partial output
is sent.
Environment variables
Resource limits can be tuned via environment variables:
| Variable | Default | Description |
|---|---|---|
DSCT_MCP_DEFAULT_COUNT |
1000 | Default packet count when count is not specified |
DSCT_MCP_TIMEOUT |
300 | Timeout per tool execution in seconds |
DSCT_MCP_WRITE_BUFFER_SIZE |
65536 | Stdout write buffer size in bytes |
DSCT_MCP_MAX_FILE_SIZE |
10737418240 | Maximum capture file size in bytes |
DSCT_THREADS |
physical CPU count | Worker threads for dsct read --filter (see --threads) |
DSCT_CACHE_DIR |
$XDG_CACHE_HOME/dsct, else $HOME/.cache/dsct |
Directory for dsct sql/dsct index database files (see SQL queries) |
Output
dsct read emits one JSON object per line:
{"number":1,"timestamp":"2024-01-15T10:30:00.123456Z","length":71,"original_length":71,"stack":"Ethernet:IPv4:UDP:DNS","layers":[{"protocol":"Ethernet","fields":{"dst":"ff:ff:ff:ff:ff:ff","src":"00:11:22:33:44:55","ethertype":2048,"ethertype_name":"IPv4"}},{"protocol":"IPv4","fields":{"ttl":64,"protocol":17,"protocol_name":"UDP","src":"10.0.0.1","dst":"10.0.0.2"}},{"protocol":"UDP","fields":{"src_port":12345,"dst_port":53}},{"protocol":"DNS","fields":{"id":4660,"qr":0,"qr_name":"Query","opcode":0,"opcode_name":"QUERY","rcode":0,"rcode_name":"NOERROR","questions":[{"name":"example.com","type":1,"type_name":"A","class":1,"class_name":"IN"}]}}]}
dsct sql emits one JSON object per result row, keyed by column name:
{"packet_number":2,"depth":1,"carrier_protocol":"VXLAN","carrier_layer_index":3}
SQLite INTEGER and REAL values become JSON numbers, TEXT becomes a
string, BLOB becomes a lowercase hex string and NULL becomes null.
The other commands emit a single JSON object or array on stdout.
SQL queries
dsct sql dissects a capture once, stores every layer in a SQLite database,
and answers SELECT queries against it. The database is built on the first
query (or explicitly with dsct index) and reused as long as the capture, the
dsct version and the dissection options are unchanged; otherwise it is rebuilt
and a {"warning":{"code":"index_rebuilt",...}} line is written to stderr.
dsct index capture.pcap # build now (prints {"type":"index",...})
dsct sql capture.pcap --schema # tables, columns, descriptions, hints
dsct sql capture.pcap "SELECT protocol, COUNT(*) AS n FROM layers GROUP BY protocol ORDER BY n DESC"
dsct sql ~/.cache/dsct/capture.pcap-3f2a9c1d8e4b0716.dsct.sqlite "SELECT COUNT(*) FROM packets" # query an index directly
tcpdump -w - -c 1000 | dsct sql - --db /tmp/live.sqlite "SELECT * FROM conversations"
- The index lives in
$DSCT_CACHE_DIR, else$XDG_CACHE_HOME/dsct, else$HOME/.cache/dsct, as<name>-<hash of the capture path>.dsct.sqlite; override with--db PATH. Reading from stdin requires--dband always rebuilds. --schemaprints the table and view definitions;--tables tcp,udpnarrows it.- Like
dsct read, output stops after 1 000 rows by default; use--count Nor--no-limit. - Expect the index to take roughly one to three times the size of the capture. Flow tracking keeps one small entry per conversation in memory while building.
Tables
| Table / view | Contents |
|---|---|
packets |
One row per packet: number, timestamp, ts, lengths, link_type, stack, max_depth, dissect_error |
layers |
One row per dissected layer: packet_number, layer_index, depth, protocol, protocol_name, offset, length |
<protocol> |
One table per protocol (ipv4, tcp, dns, gtpv1u, ...): one row per layer with a column per field, keyed by packet_number, layer_index, depth |
flows |
One row per transport conversation per depth: endpoints, packet/byte counts, first/last packet and time, tcp_stream_id |
packet_flows |
Maps transport layers to flows with direction (0 = addr_a → addr_b, 1 = reverse) |
encapsulations |
View: for every tunnelled depth of a packet, the carrier protocol (VXLAN, GRE, GTPv1-U, ...) |
conversations |
View: flows plus duration_secs |
tcp_segments |
View: TCP rows joined with packets, including seq_rel, ack_rel, next_seq, payload_len, flags_name |
Protocol table names are the lowercase, alphanumeric form of the protocol name
(GTPv1-U → gtpv1u, HTTP/2 → http2). Field columns keep their dsct read
names; fields with a display name also get a <name>_name text column
(flags_name, ethertype_name). Quote column names that collide with SQL
keywords ("type", "class", "group", "offset"). Array and object fields
are stored as JSON text. Run dsct sql <FILE> --schema to list everything.
Encapsulated and nested packets
Every layer carries an encapsulation depth: 0 for the outer packet, 1
for the first tunnelled packet (VXLAN, Geneve, GRE, GTP-U, IP-in-IP, L2TP,
MPLS, decrypted ESP, ...), 2 for a tunnel inside a tunnel, and so on. Inner
headers are ordinary rows in the same protocol tables:
# Inner IPv4 headers carried inside tunnels
dsct sql capture.pcap "SELECT packet_number, \"src\", \"dst\" FROM ipv4 WHERE depth = 1"
# Which tunnel protocol carries each inner packet
dsct sql capture.pcap "SELECT carrier_protocol, COUNT(*) FROM encapsulations GROUP BY carrier_protocol"
# Inner TCP flows carried over GTP-U, joined with the outer tunnel endpoints
dsct sql capture.pcap "SELECT t.packet_number, o.\"src\" AS outer_src, i.\"src\" AS inner_src, t.\"dst_port\" \
FROM tcp t JOIN ipv4 i ON i.packet_number = t.packet_number AND i.depth = t.depth \
JOIN ipv4 o ON o.packet_number = t.packet_number AND o.depth = 0 WHERE t.depth = 1"
# Nested fields via SQLite JSON functions
dsct sql capture.pcap "SELECT p.number, json_extract(q.value, '$.name') AS qname \
FROM dns d JOIN packets p ON p.number = d.packet_number, json_each(d.\"questions\") q"
Following streams and sequences
tcp, udp and sctp rows carry a dsct-assigned flow_id (per depth) and a
direction; both directions of a conversation share one id. TCP rows also get
payload_len, seq_rel / ack_rel (relative to the first segment seen in each
direction) and next_seq:
# Busiest conversations
dsct sql capture.pcap "SELECT * FROM conversations ORDER BY bytes DESC LIMIT 10"
# Follow one TCP stream in order
dsct sql capture.pcap "SELECT packet_number, direction, seq_rel, ack_rel, payload_len, flags_name \
FROM tcp_segments WHERE flow_id = 3 ORDER BY packet_number"
# Retransmissions: a data segment that starts before the end of an earlier segment in the same direction
dsct sql capture.pcap "SELECT DISTINCT a.packet_number FROM tcp_segments a JOIN tcp_segments b \
ON a.flow_id = b.flow_id AND a.direction = b.direction AND b.packet_number < a.packet_number \
WHERE a.payload_len > 0 AND b.payload_len > 0 AND a.seq_rel < b.seq_rel + b.payload_len"
Supported protocols
The default build currently includes 100+ protocol dissectors across link, network, transport, tunneling, and application layers.
Use dsct list to see the exact protocol set in your build; each entry reports
the protocol's layer (link, network, transport, tunnel,
application) and the specifications it is implemented against.
Errors
Errors and warnings are emitted as structured JSON on stderr.
Example:
{"error":{"code":"file_not_found","message":"failed to open capture file: test.pcap"}}
Exit codes:
| Code | Meaning |
|---|---|
0 |
Success |
1 |
General error |
2 |
Invalid arguments (including rejected or malformed SQL queries) |
3 |
File not found or permission denied |
4 |
Invalid capture format |
When the reader of stdout goes away (for example dsct read capture.pcap | head),
dsct stops writing and exits 0 without an error message. Warnings and
progress records written to stderr before that point are kept.
License
Licensed under either of Apache License 2.0 or MIT License at your option.
dsct MCP questions
What tools does dsct MCP provide?
It exposes 9 tools, including dsct_read_packets, dsct_get_stats, dsct_list_protocols, dsct_list_fields, dsct_get_schema.
How can an AI agent use dsct?
AI agents can call tools like dsct_read_packets and dsct_get_stats directly via the MCP server without needing to shell out to the CLI.
Does dsct support filtering network traffic?
Yes, you can filter packets using SQL-like syntax with operators such as AND, OR, and NOT.
Can I query packet data using SQL?
Yes, dsct can build a SQLite index of your capture, allowing you to run read-only SQL queries against it.