shack-mcp

Give Claude a ham radio. An MCP server that lets an LLM operate an amateur radio shack: query live APRS traffic, predict satellite passes, schedule SDR captures, and monitor FT8/WSPR band activity.

Status: under construction. Done: M1 (storage core), M2 (zero-hardware replay demo), M3 (live APRS: rtl_fm → direwolf → KISS TCP, plus shack fixtures import for your old packet dumps), M4 (Celestrak TLEs, pass prediction, Doppler — predict_passes over MCP), M5 (capture scheduling + cooperative hardware arbitration: priority leases, preemption hand-off, command queue), M6 (band-rotating FT8/WSPR monitor: slot-aligned WAV slicing, jt9/wsprd decoders, park/resume, get_band_activity). Next: M7 prompts + polish.

Why

Thousands of MCP servers exist for databases and SaaS tools. Approximately zero exist for RF. This one turns a $30 RTL-SDR and a rooftop antenna into a set of tools Claude can reason with:

"Who's been heard on 2m in the last hour? When's the next ISS pass over 30°, and which antenna should I grab? Is 20m open to Japan?"

Related MCP server: hamqth-mcp

Design

[RTL-SDR / HackRF]                     [Claude Code / Claude Desktop]
      │                                          │ stdio
 collector daemons (systemd)              MCP server (stateless)
      │ decoded frames/spots                    │ reads tables,
      ▼                                         ▼ enqueues commands
 ┌───────────── SQLite + WAL (shack.db) ─────────────┐
 └────────────────────────────────────────────────────┘

• Collector daemons own the radios and write decodes to SQLite. The MCP server is a stateless query-and-command layer. No LLM calls anywhere in this repo — the model lives on the client side of the protocol.

• Replay mode is first-class: recorded fixtures let you run the entire demo (and CI) with no hardware, no antenna, and no license.

• One radio, many suitors: an RTL-SDR tunes one place at a time. Priority leases with cooperative preemption arbitrate between ambient APRS listening and scheduled satellite captures.

Quick start (no hardware needed)

git clone <repo> && cd shack-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
cp .env.example .env
.venv/bin/shack db init
.venv/bin/shack demo        # replays recorded APRS traffic and serves MCP

Then attach a client — see docs/ for Claude Code (claude mcp add) and Claude Desktop config.

Learning in public

This repo doubles as a teaching project. Each milestone has a lesson in docs/lessons/ and challenge tests: run pytest -m challenge, open the matching stub in challenges/, and implement until green. The reference implementations live in src/, so the app always works even while you're mid-challenge.

Roadmap

POCSAG, ADS-B, Meteor LRPT decode chains — the collector/decoder Protocol seams are designed for community contributions. See CONTRIBUTING (coming with M7).

License

MIT