wlanpi-mcp

Official

Overview Schema Source Related Servers Discussions Admin

capture_scan

Run a live Wi-Fi packet capture on selected channels and return a dissected summary of access points and frame types, including security and signal details.

Instructions

Run a live streaming Wi-Fi packet capture and return what was on the air.

This is a streaming capture: it captures real 802.11 frames off the air (unlike scan_wlan, which asks the driver for a scan), so it reports what is actually being transmitted. The call blocks for duration_s seconds and returns a dissected summary. The raw pcapng is also saved on the device and its path returned in 'pcap_path' (fetch it with fetch_pcap_file to verify the summary against the frames). For a capture longer than the 60 s window, use the non-streaming file-capture tools (start_pcap_file/fetch_pcap_file) instead.

The result has two parts:

'aps': one row per BSSID from beacons/probe-responses, with SSID, channel, signal, 802.11 amendments, advertised TX power, full security detail — the compact 'security' label plus 'akm' (the AKM suite list), 'pairwise_ciphers', 'group_cipher' and 'pmf' — and, when the AP advertises a QBSS/BSS Load element, 'stations' (the associated client count) and 'channel_utilization' (percent).
'frames' / 'frame_types': every frame's named type/subtype counted exactly in 'frame_types', plus up to max_frames per-frame records in 'frames'. Each record has the source/destination addresses (addr1..addr4), a full radiotap decode, and — for the frames that carry one — a decoded 'result': authentication algorithm+status, association status+AID, deauth/disassoc reason, or probe/assoc SSID.

The capture is owned by this call and is stopped before it returns. If another application is already capturing on the interface, this tool subscribes to that capture read-only instead of failing; the result always says whether the role was 'owner' or 'subscriber' and reports the running config.

Single-radio caveat: where the capture interface shares a radio with the managed wlan0, channel changes fail while wlan0 scans. Any such failures come back in 'channel_issues' — treat those results as partial rather than complete.

Args: interface: Monitor-mode capture interface, always named 'wlanpiN' (e.g. 'wlanpi0'), not 'wlan0'. Use get_network_interfaces or get_capture_channels to see what exists on this device. channels: Channel numbers to hop (e.g. [1, 6, 11, 36]); 6 GHz can be given as explicit frequencies in MHz. Omit to hop every channel the adapter supports. width: Channel width in MHz: 20, 40, 80 or 160. dwell_ms: Milliseconds to dwell on each channel (50-60000). duration_s: How long to capture, 1-60 seconds. The tool call blocks for this whole window. pcap_filter: Optional BPF/pcap filter, e.g. 'type mgt subtype beacon'. max_frames: Cap on per-frame records returned in 'frames'; per-kind counts in 'frame_types' are always exact. Set 0 to skip the per-frame records and get only the AP table and counts, or a negative value for no cap (every frame — a busy capture can then return tens of thousands of records, so use the file-capture tools for a full pcap instead). Beacons dominate a busy capture, so a pcap_filter such as 'not type mgt subtype beacon' makes the record list focus on the control/data/auth exchanges.

Input Schema

TableJSON Schema

Name	Required	Default
`width`	No
`channels`	No
`dwell_ms`	No
`interface`	No	wlanpi0
`duration_s`	No
`max_frames`	No
`pcap_filter`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description takes full responsibility for behavioral disclosure—and it excels. It states that the call blocks for duration_s, that the capture stops before returning, that the raw pcap is saved to device, that results may be partial if channel_issues occur, and how the owner/subscriber modes work. These are behavioral traits the agent could not infer from the schema, and they are clearly spelled out.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries weight: differentiation, blocking behavior, result structure, ownership semantics, radio caveats, parameter guidance, and performance warnings. It is well-segmented with clear sections and front-loads the core purpose before diving into details. There is no filler or repetition of schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema (which reduces the need to explain return values), the description still previews the result structure ('aps', 'frames', 'frame_types') and key fields, covering a busy capture scenario. It addresses all 7 parameters, caveats, and edge cases (subscriber mode, channel issues, long captures). For a tool of this complexity—streaming capture, multiple return bodies, external file artifact—this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates fully. Every parameter—interface, channels, width, dwell_ms, duration_s, pcap_filter, max_frames—gets meaningful context: allowed ranges, defaults, behavior (e.g., max_frames=0 skips per-frame records, negative means no cap), and relationships to other parameters. This is exactly the kind of semantic depth an agent needs to pick correct values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'Run a live streaming Wi-Fi packet capture and return what was on the air.' It clearly distinguishes from sibling 'scan_wlan' by noting the difference between off-air capture and driver-requested scans. This precision leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance covers when to use this tool vs. scan_wlan (streaming vs. driver scan), when to switch to file-capture tools for captures longer than 60s, and when to use pcap_filter to avoid beacon dominance. It also warns about single-radio channel-change failures and explains the owner/subscriber behavior, giving the agent clear selection and invocation conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server