radiochron-mcp

radiochron.com · the chronicle of your radio.

A Model Context Protocol server that gives an AI assistant local Wi-Fi diagnostics over stdio: connection-history verdicts (reconnect loops, an AP failing key exchange, a credential mismatch), findings instead of data dumps, live signal sampling, and native WLAN collectors.

Built on the radiochron library. Pure Rust, no MCP SDK, three third-party dependencies, and no build toolchain beyond a stock rustup. The optional chronicle writes only its rotating local JSONL file; saved passwords are never read and nothing leaves the machine.

The engine, Node library, desktop app and website live independently in radiochron, radiochron-js, radiochron-electron, and radiochron-site. This repository depends directly on the Rust core. It is not distributed by radiochron-js, and RadioChron Desktop does not depend on this server.

Install

The crate is radiochron-mcp; the binary it installs is named radiochron, because a radiochron-mcp.exe in a client config reads as internal plumbing.

cargo install --git https://github.com/sergii-ziborov/radiochron-mcp

The separate radiochron-mcp npm package carries revision-checked native binaries for Windows x64, Linux x64/ARM64, Intel Mac, and Apple Silicon. It is assembled and published from this repository; radiochron-js is an independent Node library and does not contain this server.

claude mcp add radiochron -- npx -y radiochron-mcp

Releases are deliberately published from a maintainer console. Download all five native artifacts from one green CI run, point the five RADIOCHRON_MCP_BINARY_* variables at the matching binaries, then run npm pack, npm publish <archive> --access public, and verify the package from the public registry. Only after that, authenticate the official mcp-publisher, publish server.json, verify the Registry entry, and push the matching v<package-version> tag. No npm credential is stored in GitHub.

Register with an MCP client

For Claude Code, point it at the installed binary:

claude mcp add radiochron -- radiochron

Or add it to any MCP client config directly:

{
  "mcpServers": {
    "radiochron": { "command": "radiochron" }
  }
}

No arguments are required. RADIOCHRON_CHRONICLE_PATH optionally overrides the platform-local chronicle path (%LOCALAPPDATA%\RadioChron on Windows, ~/Library/Application Support/RadioChron on macOS, or the XDG state directory on Linux). The transport is newline-delimited JSON-RPC 2.0 over stdio.

Tools

Ten portable tools with machine-readable input/output schemas, structured results and truthful MCP safety annotations. Windows exposes an eleventh tool, wifi_history, backed by WLAN AutoConfig.

Tool	Arguments	Returns
wifi_status	—	Every WLAN interface and, for the associated one: SSID, BSSID, PHY type (ht/vht/he/eht), signal quality, estimated RSSI in dBm, rx/tx rates
wifi_networks	refresh_scan?: boolean<br>detail?: "summary" | "full"	Nearby BSS plus cache age, scan completion, per-interface errors, WPA2/WPA3/OWE, cipher, PMF, width and load fields
wifi_analyze	refresh_scan?: boolean	Findings, not records. Co-channel contention, crowded-channel association, weak signal, band-steering and roam candidates, insecure security, hidden SSIDs, scan-quality problems
wifi_history (Windows)	within_seconds?: number<br>max_events?: number<br>include_events?: boolean	Why it dropped earlier. Reads the WLAN AutoConfig event log and returns a verdict: reconnect loops, an AP repeatedly failing key exchange, a suspected credential mismatch
wifi_sample	interface_guid?: string<br>duration_seconds?: 1..120<br>interval_ms?: 250..60000	Cancelable sampling with progress; collector errors remain distinct from disconnects
wifi_scan	—	Triggers a standard native scan and reports per-interface completion/failure
connectivity_diagnose	DNS/TCP/Internet endpoints plus optional portal, TLS and quality targets	Separates radio, authentication, DHCP/static IP, gateway, DNS, TCP, captive portal, TLS, packet loss/jitter and Internet. TLS certificate validation lives in the agent transport; MCP reports that stage as unknown.
chronicle_start	interval_seconds?: 1..300<br>signal_threshold_db?: 1..50	Starts the local rotating change-only recorder
chronicle_stop	—	Stops and flushes the recorder
chronicle_status	—	Recorder state, path and latest error
chronicle_recent	max_entries?: 1..1000	Recent entries from active and rotated files

Prefer wifi_analyze. On a real 43-BSS environment it answers in ~800 bytes where the full BSS list costs ~41 KB — because it returns the conclusion, not the evidence. Every finding carries a caveat field stating why it might be wrong; that is part of the payload on purpose, since a bare severity invites over-trust and several of these signals are genuinely weaker than they look.

Two behaviours worth knowing about wifi_networks: the driver cache can be empty, so a first empty read is retried once behind a real scan (the refresh object says what completed) rather than reported as "no networks"; and summary is the default — ask for full (raw IEs, rates, capability bits) only when you need those fields.

Deliberately not exposed

The parent project grew collectors that are unsafe to hand to an autonomous model. They are not part of this server's tool surface, and calling them returns -32601 unknown tool:

• plaintext saved Wi-Fi keys — a model must not be able to read and leak credentials
• adapter MAC change / adapter restart / computer rename — privileged, disruptive, can drop the operator off the network
• active LAN sweeps — emit probe traffic, trip IDS on managed segments
• external AI-review shell-out — arbitrary process execution and off-box data flow

Why no SDK

The official rmcp crate would add tokio, schemars, and a mandatory chrono whose clock feature depends on windows-link/raw-dylib — reintroducing the exact build requirement this project exists to avoid. The stdio transport is a few hundred lines over serde_json instead, so the server builds on nothing but rustup.

Platform

The MCP binary runs on Windows, Linux and macOS. It uses WLAN API on Windows, nl80211 on Linux, and CoreWLAN on Apple systems, including Apple Silicon. Windows alone exposes WLAN AutoConfig event history; all other tools remain available on macOS and Linux.

Safety and privacy

SSIDs, BSSIDs, MAC addresses and event logs are sensitive. This server is local-first, has no telemetry, and transmits nothing off the machine. Only run scans against networks you own or are authorized to test. It is not a packet sniffer, a geolocation system, or offensive Wi-Fi tooling.

License

Licensed under the MIT License. The underlying radiochron Rust core remains separately dual-licensed under MIT or Apache-2.0.