fishball-sdr-mcp
An MCP server that turns a Fishball7020/PlutoSky SDR (Zynq-7020 + AD9361) into tools an AI assistant can operate over libiio to inspect, measure, capture and transmit.
Inspect the radio —
sdr_get_status(LO, rates, gain, RSSI, temperature, firmware),sdr_tx_chain_state,sdr_tx_status,sdr_board_health(Zynq XADC rails and die temp),sdr_list_devices,sdr_read_attribute.Tune and configure RX —
sdr_tunesets the receive LO (70 MHz–6 GHz);sdr_configure_rxsets sample rate, RF bandwidth, gain mode, and manual gain.Engage the FPGA channel filter —
sdr_set_fpga_filterswitches the decimate-by-8 FIR in or out of the receive path.Measure the spectrum —
sdr_spectrumreturns peaks, noise floor and an optional ASCII plot;sdr_scan_bandsteps the LO across a range to find receivable signals.Capture IQ —
sdr_capture_iqwrites interleaved int16 samples plus a SigMF metadata sidecar to disk and returns the paths (never samples inline).Transmit —
sdr_tx_tone(DDS carrier),sdr_transmit_iq(file: int16/complex64/wav, optionally cyclic),sdr_transmit_waveform(tone, two-tone, chirp, noise), andsdr_tx_disableto silence everything immediately.Safety and formatting — transmits pass a band/power safety gate with
override_reason/force, transmit can be disabled withSDR_MCP_ALLOW_TX=0, and every tool acceptsresponse_formatofmarkdownorjson.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fishball-sdr-mcp what FM stations can I actually receive here?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fishball-sdr-mcp
Sibling repository. This server drives the radio. Its sibling, fishball7020-fpga-devkit, builds the firmware that runs on it — HDL, kernel, bootloader, and a 54-lesson course on how the whole thing works. Use them together: the devkit changes what the board is, this server changes what it is doing.
Ask an LLM what's on the air, and have it actually go and look.
An MCP server for the Fishball7020 / PlutoSky software-defined radio (Zynq-7020 + AD9361). It turns the board into 21 tools an assistant can use: tune it, sweep a band, measure a spectrum, capture IQ, engage the FPGA channel filter, and transmit.
New to any of that? A software-defined radio is a receiver and transmitter whose behaviour is decided in software rather than by fixed circuitry — you tell it a frequency and it tunes there. MCP is a standard way of exposing a set of actions to an AI assistant, so it can operate something directly rather than describe how you might. IQ is the raw form radio samples take: two numbers per sample, which together carry both the strength and the timing of the wave. Put together: this lets an assistant use the radio.
> what FM stations can I actually receive here?
sdr_scan_band(start_hz=87500000, stop_hz=108000000)
| Frequency | Level | Above floor |
|------------|------------|-------------|
| 102.1 MHz | -31.5 dBFS | 73.9 dB |
| 100.7 MHz | -44.2 dBFS | 61.2 dB |
...The board's firmware and FPGA build system live in a companion repository, fishball7020-fpga-devkit.
I want to…
I want to… | Start here |
get it running with Claude Desktop or Claude Code | Quick start, or the devkit's walkthrough, Claude and the radio |
see every tool and what it does | |
point it at a board on a different address | Configuration — |
transmit, safely | Transmitting — read this one before keying anything |
know why a transmit was refused, and how to go ahead anyway | The safety gate — |
work out what my RF ports are connected to |
|
turn transmitting off entirely | Turning transmit off — |
understand why a capture is int16 and what full scale is | |
run the tests | |
know what this board actually measures like | |
decode aircraft (ADS-B, 1090 MHz) | the devkit's |
script a repeatable bench measurement (set, transmit, capture, fetch) from Python | the devkit's automation server: gRPC on the board, port 7020, with the transmit rules enforced on the board; a complete example sweeps both loopbacks to a CSV, and a receive beamformer uses several boards on one reference clock as one antenna array. It and this server share one radio: while either holds a buffer, the other is refused |
see the board's links, die temperatures, radio settings and CI in a side pane while you work in Claude Code | the devkit's Claude Code pane: |
drive this board from MATLAB or Simulink instead | the devkit's MATLAB guide and its Simulink blocks |
change the firmware itself, not just drive it | the sibling fishball7020-fpga-devkit |
Related MCP server: gnuradio-mcp-server
Quick start
# run from: wherever you want the server to live (e.g. ~)
git clone https://github.com/matsvandamme/Fishball7020-mcp.git
cd Fishball7020-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
claude mcp add -s user fishball-sdr -- "$PWD/.venv/bin/fishball-sdr-mcp"-s user registers the server for every Claude Code session you start.
Without it, claude mcp add registers it only for sessions started in this
folder, so a session in the devkit, say, would not see it.
-e . installs the package into the venv, which puts a fishball-sdr-mcp
launcher on the venv's bin/. Use that rather than python -m fishball_sdr_mcp: your MCP client starts the server from its own working
directory, not this one, so a bare -m invocation will not find the package.
Note the venv records absolute paths. If you move this directory, delete
.venv and recreate it.
Then ask for sdr_get_status. If the board answers, you're done.
Not sure where your board is? iio_attr -S scans and prints it. The default is
ip:fishball.local, the name the board announces on whichever link it is on:
USB, your router, or a cable straight to your PC.
Working on this server
.claude/skills/fishball-sdr-mcp/ is an Agent Skill:
if you use Claude Code it loads automatically here, carrying the server's own
conventions and the hardware facts that keep catching people out — the power
amplifier and what it means for a loopback, 12-bit receive against 16-bit
transmit, why hardwaregain is an index rather than a gain, the IIOD protocol
gotchas, and that stdout belongs to JSON-RPC. Harmless if you don't use an agent.
Requirements
Python 3.10+, and a Fishball7020 reachable over libiio. That's it.
The board is reached over libiio's network protocol using plain sockets, so
there is no pylibiio to install and no libiio version to match against your
firmware. numpy is used for the FFT if it happens to be importable, and a
pure-Python transform otherwise — the server runs with only mcp installed.
Tools
Look at things — sdr_get_status · sdr_spectrum · sdr_scan_band ·
sdr_capture_iq · sdr_board_health · sdr_list_devices ·
sdr_read_attribute · sdr_find_board
Change things — sdr_tune · sdr_configure_rx · sdr_set_fpga_filter ·
sdr_sample_gpio · sdr_sample_gpio_clock
Transmit (enabled; set SDR_MCP_ALLOW_TX=0 to forbid) — sdr_tx_tone · sdr_transmit_iq ·
sdr_transmit_waveform · sdr_sample_gpio_clock · sdr_check_rf_setup (its
loopback probe transmits at −41 dBm on the receive LO; passive when the gate is
closed) · sdr_tx_status · sdr_tx_chain_state · sdr_tx_disable
What this board's transmitter actually produces — ten modulations sent from a Fishball7020 and received on a HackRF One, with spectra, constellations, EVM and spur attribution — is measured in the devkit's modulation gallery, along with the code to repeat it.
Ask the bib reader — sdr_rfid_field reports what the EPC Gen2 reader
has in front of its antenna: which chips are answering, how often, how
strongly, their factory serial numbers, and what the reader makes of the
field. It asks the reader's own web server rather than the radio, because
the reader owns the board while it runs and two things driving one board is
how you get a reader that stops reading. Start it first, from the
Fishball7020-ucode8-reader
repository:
# run from: that repository's root
.venv/bin/python host/gui.py --read tidEvery tool takes response_format: markdown to read, json to parse.
Three design decisions worth knowing
sdr_capture_iq writes a SigMF pair and returns both paths. It never
returns samples inline — even a short capture is megabytes, and putting that
through a context window helps nobody. The samples go to <name>.sigmf-data as
interleaved little-endian int16, which GNU Radio reads as a file source of
type short and which sdr_transmit_iq accepts straight back.
Beside it goes <name>.sigmf-meta, because a capture returned through MCP
outlives the conversation that produced it and whoever opens it next cannot
scroll back to find the sample rate. The sidecar carries rate, centre frequency,
gain, AGC mode, RSSI, bandwidth and the capture statistics — every one read
back off the board after configuration rather than echoed from the request,
since gain quantises to the AD9361's own table and rf_bandwidth snaps to what
the filter design supports.
It also records the one thing SigMF has no field for: receive full scale on this board is ±2047, not ±32767, because the converters are 12-bit sign-extended into an int16. Divide by 32768 and every absolute level is 24 dB low — uniformly, so nothing looks wrong.
sdr_set_fpga_filter works by setting a sample rate. There is no "filter
on" attribute anywhere. Writing cf-ad9361-lpc's sampling_frequency to one
eighth of the converter rate is precisely what drives GP_CONTROL bit 0 and
flips the bypass mux in the bitstream. See
the channelizer write-up.
sdr_sample_gpio exposes a feature of the devkit firmware, not of the chip.
The AD9361's transmit DAC is 12 bits and reads only the top 12 of each 16-bit
sample, so the bottom four are discarded. Devkit firmware routes them to four
expansion-header pins instead, making digital outputs whose edges are locked to
the RF sample that carried them — a clock, a frame marker, a sync line. The
tool turns that routing on and off; what the pins do is whatever pattern you
put in the low nibble of the samples you transmit, OR-ed in last so nothing
rescales it away. sdr_sample_gpio_clock writes such a pattern for you — a
square wave, and optionally a one-sample frame marker — and refuses a buffer
length that is not a whole number of cycles, because that produces a clock
which stutters once per buffer wrap. Firmware without patches 0006/0007 has no such attribute and
the tool says so rather than failing obscurely. See
the feature reference.
Receive levels are dBFS against a 12-bit converter, so full scale is ±2047. Transmit is not: the DAC takes the full 16-bit range. That asymmetry is measured, not assumed — see Notes from the hardware.
Configuration
Variable | Default | Meaning |
|
| Where the board is. A name, not an address, so it survives DHCP moving the board |
|
| Socket timeout, seconds |
|
| Where |
| unset (permitted) | Set to |
| unset | Restrict TX, e.g. |
| unset | Have TypeSafe check the reason given for overriding the safety gate |
| unset | Leave the transmitter exactly as found |
If your board is not on 192.168.2.1. That address is the USB Ethernet
gadget. A board plugged into a router has a second, different address on eth0,
and you do not have to know it — the board advertises itself over mDNS, so
ip:fishball.local works as a URI and keeps working when the address
changes. (fishball is the devkit's default hostname; a board on an
unpatched rootfs still answers to pluto.local.)
A board cabled straight to your PC has no router to give it an address:
let the PC serve DHCP (NetworkManager's shared mode), as in the devkit's
a direct cable to your PC.
ip:fishball.local then finds it there, and sdr_find_board checks this
machine's neighbour table as well. The cable is not much faster: the board's
CPU, not gigabit, limits streaming, to 12 MS/s at 16 bits through iiod
(measured).
# run from: your HOST
iio_info -s # what is out there, with addresses
export SDR_MCP_URI=ip:fishball.local # or ip:192.168.1.50Changing the board's own address is a devkit matter rather than an MCP one:
changing the board's IP address
covers the four routes, including why editing uEnv.txt on the SD card looks
like it works and does not.
.mcp.json.example is a drop-in config if you'd rather not use claude mcp add.
Transmitting
Transmitting is enabled. It used to be off unless you opted in; the board's
owner asked for it available without ceremony, so the switch is now the other
way round — set SDR_MCP_ALLOW_TX=0 to turn it off.
That puts the responsibility on you rather than on a flag. This board reaches about +19 dBm (roughly 80 milliwatts) and tunes the FM broadcast band, where transmitting without a licence is illegal in most countries. Two consequences worth internalising before the first call:
Into an antenna, you are a transmitter, and the law applies.
Into a cable, you can destroy the board — see the warning below.
Before you transmit: what is connected?
sdr_check_rf_setupRun this whenever you are about to transmit and do not already know how the board is cabled. It reports what the ports appear to be attached to.
It is honest about a real limit. This board has no detector on the transmit socket, so whether an antenna is attached there cannot be measured — not by this tool, not by anything. What it can do it does: it listens on the receive port for ambient radio (a sign an antenna is attached to that), and sends a deliberately tiny probe to see whether a cable carries it back. Measured, the two cases are unambiguous: about 4–7 dB of return with no cable, about 70 dB through a 20 dB attenuator.
The probe transmits at −41 dBm, roughly a ten-thousandth of a milliwatt — far
too little to matter off an antenna, and 44 dB below what the receiver can
survive. probe=false keeps it entirely passive.
Choosing a channel
The board has two independent transmit chains, TX1 and TX2. sdr_tx_tone,
sdr_transmit_iq and sdr_transmit_waveform all take channel:
| Transmits from |
| TX1 |
| TX2 |
| both ports, the same waveform on each |
There is no default (since 2026-09-30; it used to be "both"): a transmit call
must name the port it keys, and one that does not is refused before the radio is
touched. A default drives a port nobody named — the same defect the devkit's
tone.py had, fixed the same way.
The safety gate: bands, power, and overrides
Before sdr_tx_tone, sdr_transmit_iq or sdr_transmit_waveform touches the
radio, the server checks two things in code:
Band. Everything the transmit emits must sit inside one of the EU licence-free bands: 433.05–434.79 MHz, 863–870 MHz, 2400–2483.5 MHz or 5725–5875 MHz. "Everything" includes the leakage at the local oscillator (LO, the carrier frequency the chip is tuned to), the chirp's sweep, and, for an IQ file, the whole width its sample rate allows, because the server cannot see what is in the file.
Power. The estimated output must stay under that band's legal limit: +10 dBm at 433 MHz, +14 dBm at 868 MHz and 5.8 GHz, +20 dBm at 2.4 GHz. The estimate is +19 dBm at full output, less the attenuation and the amplitude (
scale). It is not a measurement, and an antenna's gain is not in it.
A transmit that fails either check is refused, with the reason. You then have two ways on:
Argument | What happens |
| Transmits, and logs the reason. If |
| Transmits anyway, with or without a reason, whatever the gate or TypeSafe said. The reply opens with a WARNING naming what was overruled, and the log records it as forced. The gate advises; you decide. |
TypeSafe is only asked about overrides, so a transmit inside the rules never
waits on the network. Without a key, override_reason is taken at its word and
logged as unchecked. The key goes in the server's environment, like every
variable here (see below), and is read on every override, so it never needs to
be in a prompt.
What it looks like, with a key set, asking for a tone at 100 MHz (the FM broadcast band) with the reason "just testing, it's fine":
ERROR: Refusing to transmit a tone: 100.0000-100.1000 MHz is not wholly inside a
licence-free band (...). TypeSafe (jev-1.13.0) read the override reason as not
describing a safe setup (conducted 0.03, shielded 0.01, licensed 0.02,
radiates 0.43). ...Each number is TypeSafe's probability that the reason says so: that the port is cabled with nothing radiated, that it is shielded, that a licence covers this frequency, and that it goes out of an antenna. It accepts at 0.8 or above for one of the first three, with "radiates" under 0.5 unless the licence covers it. Those thresholds are chosen, not tuned.
The gate does not cover sdr_check_rf_setup's −41 dBm probe or
sdr_sample_gpio_clock. SDR_MCP_TX_BANDS, if set, still applies on top, and
force does not lift it.
Turning transmit off
The variable is read from the server's environment at startup, not from the shell you type in, so exporting it in your terminal does nothing. Put it in the MCP registration:
# run from: anywhere - the path below is absolute
claude mcp remove -s user fishball-sdr
claude mcp add -s user fishball-sdr -e SDR_MCP_ALLOW_TX=0 -- \
/absolute/path/to/Fishball7020-mcp/.venv/bin/fishball-sdr-mcpor in .mcp.json:
{ "mcpServers": { "fishball-sdr": {
"command": "/absolute/path/to/Fishball7020-mcp/.venv/bin/fishball-sdr-mcp",
"env": { "SDR_MCP_ALLOW_TX": "0" } } } }Restart your MCP client afterwards — the environment is fixed when the
server process starts, so editing the registration mid-session changes nothing
until the client restarts. sdr_tx_status reports what the running server
actually believes.
sdr_tx_disableandsdr_tx_statusare never gated. An off switch that can be unavailable is not an off switch.sdr_tx_disablealso runs on server shutdown, so a crashed client cannot leave the board transmitting a cyclic buffer.cyclic=truekeeps transmitting after the call returns. That's the point of it, and it still surprises people;sdr_tx_statusshows what's running.SDR_MCP_TX_BANDSrestricts transmission to named frequency ranges, e.g.2400-2483.5(MHz), on top of everything above, including the safety gate andforce.Every transmit call - tones, buffers, the RF-setup probe and the GPIO clock - is logged to stderr with frequency, gain, channel and sample count, and every safety-gate decision with its reason (
TX GATE pass,refused,override ACCEPTED/REJECTED,FORCED).
A TX→RX loopback without an attenuator will destroy your receiver. The receiver is the fragile end: the AD9361's RX input is rated to roughly +2.5 dBm. And this board is sold in a variant carrying a Mini-Circuits PGA-102+ power amplifier — 17.7 dB of gain at 50 MHz falling to 10.4 dB at 6 GHz, P1dB +17.5 dBm. Plan for about +19 dBm flat out, some 16 dB above what its own receive port survives. That is an estimate, scaled up from a quieter measurement and capped at the amplifier's compression point, not a power-meter reading. Fit at least 20 dB. More is just as safe, but 20 dB also measures best: the board leaks some transmit signal straight into its own receiver, and through 50 dB that leak is as strong as the loop above about 1.5 GHz (measured). Connect with TX attenuation at maximum and raise power in steps.
Testing
# run from: the repo root
.venv/bin/python evaluation/smoke_test.py # protocol only, no radio
.venv/bin/python evaluation/smoke_test.py --live # also call read-only toolsThis stands in for MCP Inspector, which needs Node 18 while Ubuntu 22.04
packages Node 12. It speaks JSON-RPC over stdio using only the standard library
and checks the handshake, tool schemas and annotations, that the transmit gate
refuses and names its variable, that diagnostics stay off stdout, and — with
--live — that every read-only tool returns real data. It never transmits and
never retunes your radio.
evaluation/questions.xml holds ten evaluation questions with verified answers,
per the mcp-builder
skill this server was built to.
Notes from the hardware
Things that cost real time to work out, recorded so they cost you none.
Two units appear repeatedly. dBm is absolute power: 0 dBm is one milliwatt, +19 dBm about 80 mW, −41 dBm a ten-thousandth of a milliwatt. dBFS is how loud a received signal is compared with the largest the converter can represent, so it is always negative. Both are decibels, meaning ratios that add: 10 dB is ten times the power, 20 dB a hundred, 30 dB a thousand.
The IIOD channel mask is fixed-width. Exactly 8 hex characters per 32 scan
channels. 00000003 enables channels 0 and 1. Both 3 and
0000000000000003 fail with -22 EINVAL and no hint as to why.
WRITEBUF is acknowledged twice — once before the payload and once after.
Skip the first status and the stream desyncs, with your samples arriving as the
next "response line".
Transmit full scale is 16-bit; receive is 12-bit. Measured over a cable: digital amplitudes of 8191 and 32767 produced +12.7 dB and +24.8 dB relative to 2047 (expected +12.0 and +24.1) with no rise in distortion. Scaling transmit to ±2047, as the receive side does, emits 24 dB low.
TX gain order no longer matters — on current firmware. Starting a TX
buffer fires the kernel's preenable hook, which on devkit firmware built
before October 2026 unmuted by restoring a cached attenuation, overwriting
whatever you wrote beforehand: asking for -10 dB put -60 dB on the wire.
patches/0005
fixes that — the cache is now restored only if nothing has been set since the
mute, so setting a gain before the stream works, and starting a stream having
set nothing still brings back your last gain. The transmit tools here set gain
after the stream regardless, which is correct either way.
The TX mute costs no output power. Swept over a 50 dB attenuated loopback: commanded and applied attenuation matched to 0.01 dB at every point including 0 dB, and received level tracked the commanded gain across a 40 dB range within 1.9 dB. Full output is fully available.
An empty serial makes other tools refuse the board. This server connects by
URI and is unaffected, but SDRangel identifies Plutos by serial number, and
devkit firmware built before September 2026 reported an empty one — the board's
Winbond W25Q128 flash never emits the SPI-NOR-UniqueID line the boot script
greps for. SDRangel then lists PlutoSDR0 TBD and fails with open serial TBD failed. Current devkit firmware mints a persistent serial on first boot without
changing the gadget MAC or interface name; sdr_get_status reports it. If you
see a TBD, reflash from the current
devkit.
Two tools cannot hold the board at once. When SDRangel (or anything else)
opens the Pluto over USB, the firmware reconfigures the composite device and
the USB Ethernet gadget disappears — so ip:192.168.2.1 stops answering and
every tool here fails with a connection error until that application closes.
Not a fault; just mutually exclusive.
Something on the board may be changing your gain. /mnt/jffs2 is
persistent and /mnt/jffs2/autorun.sh runs at every boot, so a helper script
there survives reflashing and appears nowhere in the firmware source. A common
one polls the TX buffer and applies a fixed gain a second or two after any
stream starts — a workaround for the clobbering described above, and no longer
needed. It overrides this server's gain silently, and on a board with the
PGA-102+ power amplifier the 10 dB such scripts typically use is about +13 dBm
at the SMA against a +2.5 dBm receive port. The devkit's
tools/selftest/sdr_selftest.py --ssh lists what is there.
A retune is not visible in the samples until the buffer is rebuilt. This
server is unaffected, and the reason is worth knowing before anyone changes it:
every capture here does its own OPEN, reads, and closes, so each one starts a
fresh buffer at the current settings. Hold a buffer open across a retune instead
and the old samples come out first — measured over USB on the devkit's
long-lived iio_readdev stream at 2.304 MSPS in 4096-sample frames, a
commanded 500 kHz retune left the tone at the old offset for thirty-four
more frames and only moved on the thirty-fifth, with altvoltage0 frequency
reading the new value the whole time. Reading the register back is not
evidence the retune reached your samples. pyadi-iio's rx_destroy_buffer()
exists for this.
Receive rf_port_select accepts only A_BALANCED. The chip advertises
twelve in rf_port_select_available — A/B/C balanced, the six single-ended
halves, and TX_MONITOR1/2, which would point the receiver at the board's own
transmitter with no cable — and this firmware refuses every one of them but
A_BALANCED with Invalid argument (22), from an idle ENSM state as readily as
from a running one. filter_fir_en 1 is refused the same way until coefficients
are loaded through filter_fir_config. Neither is used by this server; they are
recorded because _available reads like a menu and is not one.
The transmitter idles hot on stock firmware. The AD9361 comes up in ENSM
fdd with the synthesiser running and 10 dB of attenuation, so the TX port
leaks LO with nothing in the DAC. This server quiets it at startup unless
transmitting is enabled; the companion devkit
fixes it properly in firmware.
License
Same terms as the companion devkit: GPL-2.0.
Available Tools
16 toolssdr_board_healthBoard healthARead-onlyIdempotent
Read the Zynq XADC: internal supply rails and die temperature. Useful for checking the board is healthy, or whether it is running hot.
Inputs: response_format. Returns: result
sdr_capture_iqCapture IQ to a fileA
Capture raw IQ samples and WRITE THEM TO A FILE, returning the path plus level statistics. Samples are never returned inline - even a short capture is megabytes. The file is interleaved little-endian int16 (I,Q,I,Q,...), which GNU Radio reads as a file source of type short, and which sdr_transmit_iq accepts directly.
Inputs: samples, filename, channel_pair, response_format. Returns: result
sdr_configure_rxConfigure the receiverAIdempotent
Set any of: converter sample rate (Hz), RF analog bandwidth (Hz), gain control mode, and manual gain (dB). Omitted settings are left alone. Values are checked against the radio's own '*_available' attributes, so an illegal request is rejected with the legal options rather than silently ignored.
Manual gain only applies when gain_mode is 'manual'.
Inputs: gain_db, gain_mode, bandwidth_hz, sample_rate_hz, +1 more. Returns: result
sdr_get_statusRadio statusARead-onlyIdempotent
Report how the SDR is currently configured: RX local oscillator, converter and delivered sample rates, whether the FPGA channel filter is engaged, RF bandwidth, gain, RSSI, die temperature and firmware version. Start here.
Inputs: response_format. Returns: result
sdr_list_devicesList IIO devicesARead-onlyIdempotent
List every IIO device, channel and attribute the board exposes. Use this to discover exact names before calling sdr_read_attribute, or to check what a particular firmware build provides.
Inputs: response_format. Returns: result
sdr_read_attributeRead an IIO attributeARead-onlyIdempotent
Read any single IIO attribute by name - an escape hatch for anything the other tools do not cover. Use sdr_list_devices to find valid names. Reading an attribute called '_available' shows the legal values for ''.
Inputs: device (required), attribute (required), output, channel, +1 more. Returns: result
sdr_scan_bandScan a frequency rangeA
Step the LO across a range and report the signals found, strongest first. Use it to discover what is receivable - for example which FM broadcast stations are audible at this location.
The radio is left tuned to the last step, so re-tune afterwards if you care where it sits. A wide scan at a low sample rate takes many steps and is slow; raise the sample rate to cover ground faster at coarser resolution.
Inputs: stop_hz (required), start_hz (required), samples, step_hz, +3 more. Returns: result
sdr_set_fpga_filterEngage or bypass the FPGA channel filterAIdempotent
Switch the FPGA's decimate-by-8 channel filter into or out of the receive path.
On firmware built from this devkit's channelizer patch, engaging it selects a sharp FIR that removes everything outside the wanted channel, and drops the delivered rate to one eighth of the converter rate. It works by writing the cf-ad9361-lpc sample rate, which is what drives GP_CONTROL bit 0 and the bypass mux in the bitstream - there is no separate on/off attribute.
Bypassing is the way to A/B whether the filter is really doing anything: a neighbouring signal that reappears when bypassed is the proof.
Inputs: engaged (required), response_format. Returns: result
sdr_spectrumMeasure the spectrumA
Capture IQ and return the strongest signals as a table of frequency and level, with the noise floor and capture statistics, optionally with a compact ASCII plot. This is the tool for 'what is on this frequency right now'.
Levels are dBFS referred to the 12-bit converter's full scale. Only the sample rate's worth of spectrum around the current LO is visible - use sdr_scan_band to cover more.
Inputs: plot, peaks, samples, channel_pair, +1 more. Returns: result
sdr_transmit_iqTransmit an IQ fileADestructive
Transmit an arbitrary IQ waveform read from a file on this machine.
Formats: 'int16' interleaved little-endian I,Q (what sdr_capture_iq writes), 'complex64' (what a GNU Radio file sink writes), 'wav' (2 channels as I and Q), or 'auto' to infer from the extension.
With cyclic=true the buffer REPEATS FOREVER and transmission continues after this call returns - use sdr_tx_disable to stop. With cyclic=false the buffer plays once. Requires SDR_MCP_ALLOW_TX=1. Only transmit into a dummy load or on frequencies you are licensed to use.
Inputs: path (required), lo_hz (required), scale, cyclic, +5 more. Returns: result
sdr_transmit_waveformTransmit a generated waveformADestructive
Synthesise and transmit a test signal without needing an IQ file: a single tone, two tones (for intermodulation testing), a linear chirp, or band-limited noise.
Always cyclic, so it repeats until sdr_tx_disable is called. Requires SDR_MCP_ALLOW_TX=1. Only transmit into a dummy load or on frequencies you are licensed to use.
Inputs: lo_hz (required), scale, shape, samples, +3 more. Returns: result
sdr_tuneSet the RX frequencyAIdempotent
Set the receive local oscillator, in Hz. Valid range 70 MHz to 6 GHz.
Note this tunes the LO, which becomes the CENTRE of the captured band. To keep the AD9361's LO leakage and DC offset out of a signal, tune deliberately off it and look at the resulting offset instead.
Inputs: frequency_hz (required), response_format. Returns: result
sdr_tx_chain_stateIs the transmitter live?ARead-onlyIdempotent
Report whether the AD9361's transmit chain is actually energised, and why. The board boots into ENSM 'fdd' with the TX synthesiser running and only 10 dB of attenuation, so TX is live from power-on even with no data in the DAC DMA - it emits LO leakage rather than silence. This tool shows the ENSM mode, TX LO powerdown state and both attenuator settings, and says plainly whether anything is being emitted. Use sdr_tx_disable to silence it.
Inputs: response_format. Returns: result
sdr_tx_disableStop transmittingAIdempotent
Stop all transmission immediately: silence every DDS tone, close any sample buffer, and power down the TX local oscillator. Never gated - it works even when transmitting is otherwise disabled, because an off switch that can be unavailable is not an off switch. Safe to call at any time.
Inputs: response_format. Returns: result
sdr_tx_statusTransmit statusARead-onlyIdempotent
Report what the transmitter is doing: whether transmitting is enabled at all, the TX LO and its powerdown state, sample rate, bandwidth, every DDS tone generator, and whether this server started a cyclic buffer that is still running. Always available, even when transmitting is disabled.
Inputs: response_format. Returns: result
sdr_tx_toneTransmit a toneADestructiveIdempotent
Transmit a continuous single-tone carrier using the FPGA's DDS generators, at an offset from the TX local oscillator.
TRANSMITS UNTIL STOPPED. Call sdr_tx_disable to stop it. Requires SDR_MCP_ALLOW_TX=1. Only transmit into a dummy load or on frequencies you are licensed to use.
Inputs: lo_hz (required), scale, tx_gain_db, tone_offset_hz, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have clearly distinct purposes, but sdr_tx_chain_state and sdr_tx_status overlap significantly by both reporting TX LO powerdown state and transmit-chain activity. Similarly, sdr_get_status and sdr_board_health both expose die temperature, which could cause selection confusion.
The names mostly follow a consistent sdr_<verb>_<noun> pattern, like sdr_capture_iq, sdr_configure_rx, and sdr_tx_disable. Minor deviations exist: sdr_spectrum and sdr_board_health are noun-style, and sdr_tx_tone vs sdr_transmit_iq mix 'tx' and 'transmit'.
Sixteen tools is slightly above the ideal range, but the count is reasonable for a full SDR server covering RX, TX, capture, scanning, and health diagnostics. Each tool addresses a real operational need rather than being redundant filler.
The RX path is well covered with tuning, configuration, filtering, capture, spectrum analysis, and scanning. However, the TX path lacks a dedicated tool to set the transmit LO frequency, which is a notable gap since TX tones and IQ transmission only operate relative to that LO.
Maintenance
Related MCP Connectors
Create RF signal projects from prompts, inspect graphs, and export IQ data.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Control your internet radio from any AI client: listeners, stream, playlists, AutoDJ, DJs, store.
Command your AI agents by voice: PTT rooms, channels, direct messages, agent email, memory (mRAG).
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables control of Software Defined Radios and decoding of radio protocols through an AI-friendly Model Context Protocol interface, supporting RTL-SDR and HackRF hardware for signal analysis and protocol decoding.3482 PyPI31MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language control of a live GNU Radio SDR flowgraph, allowing users to tune frequencies, adjust gain, capture IQ samples, analyze spectra, and detect signals through an MCP-compatible client.2MIT
- AlicenseBqualityBmaintenanceEnables AI agents to process RF signals, perform spectral analysis, and execute radar DSP primitives such as Range-Doppler processing and CFAR detection, supporting both file-based and live SDR capture.14MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read frequency, mode, and signal meter, as well as set frequency and control PTT on Icom IC-705/9700 and CI-V transceivers over the network using the RS-BA1 protocol.MIT