sdrpp-mcp

An MCP server that drives a running SDR++ instance to find, identify, decode, record and log radio transmissions. A companion skill (skill/sdr-signal-id) packages the identification workflow and reference material: signal signatures, decoder notes, hardware quirks and US legal guardrails.

It works with any SDR++ source. It was developed and tested on an RTL-SDR (Nooelec SMArTee XTR, E4000 tuner, 2.4 MS/s).

Features

• Live spectrum: snapshot the current passband with max-hold detection against an estimated noise floor, or step-sweep an arbitrary range (up to 200 retunes). Both return waterfall PNGs. Retuning lands exactly on the requested centre, sweeps report any range they failed to cover, and every tool that has to retune puts the Radio VFO back afterwards.

• Signal analysis: extract a channel and measure:

  • SNR, 99% occupied bandwidth, duty cycle and bursts

  • envelope statistics, spectral skew and flatness

  • FM deviation and FSK levels, symbol rate (snapped to standard bauds), TDMA framing

  • CTCSS and audio tones, WFM stereo pilot and RDS

  A heuristic classifier then makes a modulation guess: NFM, WFM, AM, SSB, CW/OOK, 2/4-FSK, wideband digital or carrier.

• Band plan lookup: US allocations plus named channels (NOAA WX1–7, FRS/GMRS, MURS, APRS, ACARS, AIS, ISM, etc.).

• Demodulation and recording: FM, WFM (75 µs de-emphasis), AM, USB, LSB and CW to WAV, or raw IQ (cu8 / cf32) for offline tools.

• Decoding:

  • multimon-ng: POCSAG/FLEX pagers, APRS/AFSK1200, EAS/SAME, DTMF, ZVEI, Morse, X10.

  • rtl_433: ISM-band sensors.

• Channel watching and LoRa/MeshCore decoding: continuous capture of one channel, logging every burst; LoRa is recognised by dechirping, demodulated with gr-lora_sdr, and MeshCore packets are parsed (route, hop path, payload type, node adverts with name/type/position). Encrypted message bodies are not decrypted.

• Logbook: SQLite log of identified signals, searchable, exportable as an SDR++ Frequency Manager bookmark list.

Related MCP server: GR-MCP

How it talks to SDR++

setup_sdrpp.py configures all three. Run it with SDR++ closed. It backs up each changed file next to the original as *.json.bak-<time>.

Keep the Recorder and Center Probe menus in SDR++'s sidebar collapsed (the setup script collapses them). Rigctl starts and stops the probe from a background thread, and if a recorder menu is being drawn at that moment SDR++ can abort with an ImGui PushItemFlag/PopItemFlag assertion.

Install

Requires Python ≥ 3.10 and SDR++ 1.2+ (nightly builds include the IQ Exporter).

git clone https://github.com/entitledosprey/sdrpp-mcp.git
cd sdrpp-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
python3 setup_sdrpp.py            # with SDR++ closed
sudo apt install multimon-ng rtl-433   # optional decoders

Optional, for LoRa/MeshCore decoding in watch_channel (GNU Radio + gr-lora_sdr, used through the system python3):

sudo apt install gnuradio-dev cmake pybind11-dev libspdlog-dev libfmt-dev libgmp-dev
git clone https://github.com/tapparelj/gr-lora_sdr.git && cd gr-lora_sdr
mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make -j"$(nproc)"
sudo make install && sudo ldconfig

Register the server with your MCP client as a stdio server, for example:

{
  "mcpServers": {
    "sdrpp": { "command": "/path/to/sdrpp-mcp/.venv/bin/sdrpp-mcp" }
  }
}

Skill

skill/sdr-signal-id/ is an Agent Skill (SKILL.md plus references/). To install it, copy or symlink the directory into your client's skills folder:

ln -s "$PWD/skill/sdr-signal-id" ~/.config/<client>/skills/sdr-signal-id

Example requests

Once the server (and optionally the skill) is registered with an MCP client, plain requests map onto the tools:

Tools

Frequencies accept Hz or strings such as 146.52M, 433.92 MHz or 1090m. Bare numbers below 10000 are treated as MHz.

P25 trunking

sdrpp-p25 is a companion SDR++ module that trunks P25 Phase 1/2 systems and plays the voice in SDR++. When it is running it owns the SDR's tuning: p25_status and p25_calls read its decoder's API and event log, and every tool here that would retune SDR++ refuses until the module is stopped.

Data locations

Everything lives under ~/.local/share/sdrpp-mcp/, or under SDRPP_MCP_DATA if that is set in the server's environment (run setup_sdrpp.py with the same variable so SDR++'s probe recorder writes there too):

• images/: PNG spectra and waterfalls (named <time>_<freq>_<kind>); override with SDRPP_MCP_IMAGES

• captures/: WAV and IQ recordings

• center-probe/: temporary probe files

• logbook.db: the logbook

• sdrpp.log: SDR++'s console output when started with sdr_launch

Other tools

• tools/sdrtrunk_to_sdrpp.py PLAYLIST.xml OUT_DIR: turns an SDRTrunk playlist's site frequencies into SDR++ Frequency Manager import files. SDR++ can't follow P25 trunking or decode its voice; for that use SDRTrunk, OP25 or DSD-FME (which can retune SDR++ through its rigctl server).

Frequency calibration

RTL-SDR crystals are typically off by somewhere between 0 and 50 ppm, and TCXO models by about 1 ppm. A good local reference is the ATSC digital TV pilot: an unmodulated carrier at the channel's lower edge plus 309.441 kHz. Measure the apparent offset of a few strong pilots (narrow FFT peak within ±15 kHz of the expected frequency; ignore weak channels and stations that run offset pilots). Broadcast FM carriers are too noisy for this. The correction is ppm = (true − measured) / true × 10⁶. Enter it, rounded, under Source → PPM Correction in SDR++.

Legal

The software is for receiving only. In the US, 47 USC 605 and ECPA restrict divulging or using the contents of private communications. Decoding cellular or cordless-phone content and decrypting anything are both off limits. Know your local rules.

History

See CHANGELOG.md.

License

MIT. See LICENSE.