gr4-mcp
Provides tools for building, running, and tuning GNU Radio 4 flowgraphs through the GR4 control plane, including block catalog search, graph editing and validation, session deployment and control, and reading stream data from studio sinks.
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., "@gr4-mcp build a sine source into a frequency sink flowgraph and run it"
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.
gr4-mcp
Beta release. gr4-mcp is under active development. Tools, file formats and behaviour may still change, and it has only been tested on one setup (see below). Feedback and bug reports are welcome.
An MCP server (Python, FastMCP) that lets an AI client build,
run and tune GNU Radio 4 flowgraphs through the GR4 control plane (gr4cp_server).
About
gr4-mcp is part of an attempt to make amateur television (ATV) more accessible to the public: instead of wiring signal-processing blocks by hand, you can describe what you want to an AI assistant and let it build, run and tune the GNU Radio 4 flowgraph.
More about the project: curtat.be and atv.curtat.be.
Related MCP server: GR-MCP
Installing GNU Radio 4
gr4-mcp drives an existing GNU Radio 4 installation; it does not install GNU Radio itself. Follow the official instructions:
GNU Radio 4 workspace: https://github.com/gnuradio/gnuradio4
Build guide: https://github.com/gnuradio/gnuradio4/blob/maint-4.0/docs/building.md
gr4-mcp needs the complete workspace build (the full preset), which includes the
control plane (gr4cp_server) and gr4-studio:
git clone https://github.com/gnuradio/gnuradio4.git
cd gnuradio4
cmake --preset full
cmake --build --preset fullThis installs into gnuradio4/install/full; that folder is what gr4-mcp needs
(see Where gr4-mcp finds GNU Radio 4).
Tested on Ubuntu 26.04 LTS with Python 3.14. Other platforms may work but are untested.
How it works
gr4cp_server has no graph-editing API: a session is created from one complete GRC
YAML document, and only block settings can change while it runs. gr4-mcp therefore
keeps the graph being built client-side, validates each edit against the backend's
block catalog, and submits the whole graph on deploy_graph.
Validation matters because the backend accepts these mistakes silently:
Mistake | Backend behaviour | gr4-mcp |
Unknown parameter ( | ignored | rejected with suggestions |
Unknown block type | accepted, fails at start | rejected with type variants |
Bare dynamic port ( | accepted, no data flows | mapped to next free |
Port type mismatch | fails at start | rejected at |
Studio sink without | fails at start | filled in automatically (an HTTP transport the sink supports) |
The server owns its backend: on startup it spawns gr4cp_server on a free loopback
port (the same GR4CP_PORT=0 / GR4CP_PORT_FILE handshake gr4-studio uses) and stops
it when the MCP server exits, including on SIGKILL (Linux PR_SET_PDEATHSIG).
It is independent of any backend gr4-studio is running. The backend log is
<prefix>/var/logs/gr4cp_server-mcp.log.
Setup
cd gr4-mcp
python3 -m venv --without-pip .venv # python3-venv/ensurepip is not required
pip3 --python .venv/bin/python install -e '.[test]'Where gr4-mcp finds GNU Radio 4
gr4-mcp needs the GNU Radio 4 install folder, the one containing bin/gr4cp_server
(for this workspace: /home/peter/gnuradio4/install/full). It looks, in order, at:
a folder given with
gr4-mcp --prefix PATHor registered with theset_gr4_installtool,the
GR4_PREFIXenvironment variable,the folder saved in
~/.config/gr4-mcp/config.json(set_gr4_installwrites it;GR4_MCP_CONFIGoverrides the file location),gr4cp_serveronPATH,../install/fullrelative to this repo (the workspacefullpreset).
Each accepts the install prefix, its bin/ folder or the gr4cp_server binary. If none
is found, backend_status says so and the client can ask you for the folder and call
set_gr4_install(path), which restarts the backend from it and saves the choice.
Using an existing backend (e.g. gr4-studio's)
By default gr4-mcp runs its own private backend. To share one with gr4-studio, so graphs deployed by the AI show up as Studio sessions and Studio's sessions can be read and tuned, attach to it:
the
attach_backendtool:attach_backend("http://127.0.0.1:37945"), orattach_backend("studio")to find a running gr4-studio backend from thegr4cp_server*.logfiles in the install'svar/logs;attach_backend()switches back to a private backend;at startup:
gr4-mcp --backend-url URL(or--backend-url studio), or theGR4_BACKEND_URLenvironment variable.
Attaching stops gr4-mcp's private backend (its sessions are lost). gr4-mcp never stops a backend it attached to, and leaves sessions it deployed there running when it switches away. The URL is not saved, because backend ports change on every launch.
Register with Claude Code:
claude mcp add gnuradio4 -- /home/peter/gnuradio4/gr4-mcp/.venv/bin/gr4-mcp
# or pin the install explicitly:
claude mcp add gnuradio4 -- /home/peter/gnuradio4/gr4-mcp/.venv/bin/gr4-mcp --prefix /home/peter/gnuradio4/install/fullTools
Group | Tools |
Backend / catalog |
|
Graph editing |
|
Files |
|
Sessions |
|
Data |
|
A hello_world prompt walks the client through the example below.
Hello world
new_graph("hello_world")
add_block("gr::blocks::basic::SignalGenerator<float32>", "src",
{"signal_type": "Sin", "sample_rate": 1000, "tone_frequency": 5})
add_block("gr::blocks::basic::Throttle<float32>", "throttle", {"sample_rate": 1000})
add_block("gr::studio::StudioSeriesSink<float32>", "scope")
connect("src", "throttle")
connect("throttle", "scope") # -> [throttle, out, scope, in#0]
deploy_graph() # session running, stream "scope" ready
read_stream() # scope: rms ~0.707, dominant_period_samples ~200
update_block_settings("src", {"tone_frequency": 10})
save_graph("hello_world.gr4s") # open in gr4-studioReading stream data
read_stream reads what the gr::studio::* sinks currently hold, through the
backend's /sessions/{id}/streams/{id}/http endpoint. Stream ids are the sink block
names. Results are summarized to keep them small:
Sink | Payload format | Summary |
|
| per channel: min/max/mean/rms/std, |
|
| strongest |
|
| stats and peaks of the latest row |
|
| x/y stats, downsampled points |
|
| values as-is |
max_points sets the downsampling (default 64); raw=True returns one stream's full payload.
StudioAudioSink only supports the websocket transport and cannot be read this way.
A power spectrum needs fft_size * num_averages samples (8192 by default) before its first frame.
examples/ holds the hello world with added noise as .gr4s (open in gr4-studio) and .gr4c.
Tests
.venv/bin/pytest -qtests/test_graph.py runs offline against a catalog snapshot.
tests/test_hello_world.py drives the real server over MCP stdio: it builds the graph
above, checks via read_stream that a unit sine with the right period arrives at the
scope, changes the frequency live and sees it in the stream, saves and reloads both file
formats, checks spectrum/scalar/websocket sinks, and checks the backend is stopped afterwards.
tests/test_search.py checks search_blocks ranking against the full catalog (e.g. "noise"
finds AwgnChannel and PhaseNoise first). tests/test_attach_backend.py attaches to a separately started backend via
attach_backend("studio"), deploys and reads a stream there, switches back, and checks the
attached backend and its session were left alone. tests/test_streams.py covers the payload summaries offline, tests/test_install.py the
install lookup order. tests/test_register_install.py starts gr4-mcp where no install can
be found, registers one with set_gr4_install, and checks a fresh server reuses the saved folder.
Known backend limitations
A graph whose blocks all finished still reports
running, and its blocks stop answering settings requests (timeouts).GET /blocksreports a mangledcategoryfor templated types containing::; gr4-mcp derives categories from the block id instead.Live settings reject arrays.
Not yet implemented
Studio expressions other than a plain variable name are dropped on
.gr4sload.
License
gr4-mcp is released under the MIT License.
GNU Radio 4 itself, and the GR4 logo used in docs/social-preview.png, belong to the
GNU Radio project and are covered by their own licenses.
Available Tools
23 toolsadd_blockAdd BlockA
Add a block instance to the current graph.
block_type: exact catalog id, e.g. "gr::blocks::basic::SignalGenerator". name: instance name used in connections and live settings (default: derived, e.g. signal_generator0). parameters: only values that differ from the defaults, e.g. {"sample_rate": 48000.0}.
Inputs: block_type (required), name, parameters. Returns: object
attach_backendAttach BackendA
Attach to an already running gr4cp_server (e.g. the one gr4-studio started), or go back to a private one.
url: "http://127.0.0.1:37945" (the http:// is optional); "studio" to find a running backend announced in the GR4 install's var/logs (gr4-studio writes gr4cp_server.log there); or omit it to return to a backend managed by gr4-mcp. Attaching stops the managed backend (its sessions are lost). gr4-mcp never stops an attached backend, and its sessions are shared with other clients: list_sessions shows gr4-studio's too. The URL is not saved, because backend ports change on every launch.
Inputs: url. Returns: object
backend_statusBackend StatusA
Show the GNU Radio 4 install in use, the managed gr4cp_server backend (URL, pid, log), catalog size and schedulers.
If no GNU Radio 4 install is found, the result says so: register one with set_gr4_install.
Inputs: no named parameters. Returns: object
connectConnectA
Connect source block's output port to target block's input port.
Ports may be omitted when the block has a single port of that direction. For dynamic ports pass the base name ("in") to take the next free index, or an explicit handle like "in#1". Port types must match exactly.
Inputs: source (required), target (required), source_port, target_port. Returns: object
control_sessionControl SessionB
Start, stop, restart or delete a session (default: the current graph's session).
Inputs: action (required), session_id. Returns: object
deploy_graphDeploy GraphA
Validate the graph, create a backend session from it and (by default) start it.
replace_previous stops and deletes the session previously deployed from this graph. A session whose start fails is deleted again; the runtime error is returned.
Inputs: start, replace_previous. Returns: object
describe_blockDescribe BlockA
Ports, parameters (type, default, enum choices) and type variants of one block type.
Advanced parameters (chunk sizes, compute domain, ...) are hidden unless include_advanced.
Inputs: block_type (required), include_advanced. Returns: object
disconnectDisconnectB
Remove connections from source to target (optionally only between the given ports).
Inputs: source (required), target (required), source_port, target_port. Returns: object
get_block_settingsGet Block SettingsA
Read the live settings of a block in a running session, addressed by its instance name.
Inputs: block (required), session_id. Returns: object
list_categoriesList CategoriesA
List block categories (e.g. blocks/math, blocks/filter, studio) with block-type counts.
Inputs: no named parameters. Returns: object
list_sessionsList SessionsA
List all sessions on the backend (id, name, state, last_error).
Inputs: no named parameters. Returns: result
load_graphLoad GraphA
Load a .gr4s (Studio document) or .gr4c / .grc / .yaml (GRC YAML) file as the current graph.
Unknown blocks, unsupported expressions and invalid connections are skipped and reported.
Inputs: path (required). Returns: object
new_graphNew GraphB
Start a new, empty flowgraph (replaces the current unsaved one).
Inputs: name, description. Returns: object
read_streamRead StreamA
Read the latest data from Studio sink blocks (scope, spectrum, scalar, waterfall, XY) of a running session.
stream: stream id, which is the sink block's name (default: every stream in the session). By default each stream is summarized: per-channel min/max/mean/rms/std, a dominant period in samples for time series (frequency = sample_rate / period), the strongest peaks for spectra, and at most max_points downsampled values. raw=True returns the full payload of a single stream instead (can be very large).
Inputs: raw, stream, max_points, session_id. Returns: object
remove_blockRemove BlockB
Remove a block and every connection touching it.
Inputs: name (required). Returns: object
save_graphSave GraphA
Save the graph. The extension picks the format:
.gr4s gr4-studio document (open it in Studio to view and edit), .gr4c inline GRC YAML, exactly what is submitted to the backend.
Inputs: path (required). Returns: object
search_blocksSearch BlocksA
Search the block catalog by words in the block name, category or summary; best matches first.
Every word must match. Whole words in the block name rank highest, then the first
sentence of the summary. Common radio terms are understood too, e.g. "noise" also finds
AWGN, "scope" the series sink, "fm demod" the quadrature demodulator, "mixer" the rotator.
Results are grouped per block family; each lists its concrete block_types
(one per sample type, e.g. Add, Add<complex>). Use one of
those exact strings with describe_block / add_block.
category: prefix filter such as "blocks/math" or "studio".
port_type: only blocks with a port of this type, e.g. "float32", "complex".
Inputs: limit, query, category, port_type. Returns: result
session_statusSession StatusB
State of a session (default: the one deployed from the current graph), incl. stream endpoints.
Note: a graph whose blocks all finished still reports "running".
Inputs: session_id. Returns: object
set_gr4_installSet Gr4 InstallA
Register the GNU Radio 4 install to run the backend from, e.g. "/home/peter/gnuradio4/install/full".
Accepts the install prefix, its bin/ folder or the gr4cp_server binary. The backend is restarted from that install (running sessions are lost) and the block catalog reloaded. persist=True saves it to the gr4-mcp config file so later runs use it too (the GR4_PREFIX environment variable still takes precedence there).
Inputs: path (required), persist. Returns: object
set_parametersSet ParametersA
Set parameters on a block in the graph (validated against the catalog).
A value of null resets the parameter to the block default. This edits the graph only; use update_block_settings to change a running session.
Inputs: name (required), parameters (required). Returns: object
show_graphShow GraphA
Current flowgraph: blocks with their set parameters and ports, plus connections.
include_grc adds the GRC YAML that deploy_graph would submit.
Inputs: include_grc. Returns: object
update_block_settingsUpdate Block SettingsB
Change settings of a block in a running session, e.g. {"tone_frequency": 10.0}.
When the session belongs to the current graph, values are validated against the catalog first and also written into the graph so a later save/deploy keeps them.
Inputs: block (required), settings (required), mode, session_id. Returns: object
validate_graphValidate GraphA
Check the graph locally: missing blocks, port counts, unconnected blocks, no sink.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools have a clearly distinct target: catalog browsing (search_blocks, describe_block, list_categories), graph editing (add_block, connect, set_parameters), and runtime control (deploy_graph, control_session, read_stream). The one risky pair is set_parameters vs update_block_settings and get_block_settings vs show_graph, but their descriptions explicitly contrast graph-edit vs live-session semantics. Only minor boundary friction remains.
The dominant pattern is snake_case verb_noun (list_categories, add_block, remove_block, save_graph, deploy_graph, read_stream). Deviations are minor and readable: noun-first status tools (backend_status, session_status) and a few verbless/bare-verb names (new_graph, connect, disconnect). No casing mixing.
23 tools is on the heavy side, but the domain genuinely spans four sub-areas (block catalog, graph editing, deployment/sessions, backend install management) and each tool covers a real operation. Nothing looks redundant enough to remove, though a couple of status tools could conceivably be merged.
The lifecycle is well covered end to end: discover blocks, build/edit a graph, validate, save/load, deploy, control the session, and read live data, plus backend install and attach management. Small gaps exist around exposing graph export/serialization details or bulk session cleanup, but agents can work around them with existing tools.
Related MCP Connectors
Create RF signal projects from prompts, inspect graphs, and export IQ data.
Generate, inspect, and manage Flowstep UI designs directly from your AI assistant.
Manage SRG+ hubs, channels, content, assets, users, and workspaces from any MCP-aware AI agent.
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
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.3437 PyPI33MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables natural language-driven creation and management of GNU Radio flowgraphs with validated block connections and parameter configurations. It provides tools for searching the GNU Radio block library, detecting SDR hardware, and generating functional signal processing code.8MIT
- 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
- AlicenseBqualityDmaintenanceConnects AI assistants to the Node-RED Admin API, enabling flow inspection, node management, graph analysis, debug capture, and rollback operations through natural language.37MIT