GR-MCP

GR-MCP is a Model Context Protocol (MCP) server that exposes GNU Radio's block library, flowgraph management, and code generation to LLM clients. It enables natural language-driven flowgraph creation through validated tool calls that enforce GNU Radio's type system and connection rules. The server has been tested with Claude, Codex, and locally-hosted models via llama.cpp.

Statement of Need

GNU Radio provides an open-source framework with hundreds of signal processing blocks for applications ranging from FM receivers to complex digital communication systems. However, the steep learning curve associated with its block library, parameter configuration, and connection rules presents a barrier to rapid prototyping. When LLMs are used for GNU Radio flowgraph generation without domain-specific tooling, they produce syntactically plausible but frequently non-functional outputs with type mismatches, invalid parameters, and improper connections.

GR-MCP bridges this gap by providing LLMs with structured access to GNU Radio through the Model Context Protocol. The type system pre-validates connections before they are made, the block database provides accurate parameter specifications, and validation tools catch errors before code generation. The system supports both cloud-based LLMs and local models served via llama.cpp for offline operation.

Installation

GR-MCP requires Python 3.10 or later and a working GNU Radio 3.10+ installation.

1. Install GNU Radio

sudo apt install gnuradio

For other operating systems and versions, see the GNU Radio installation guide.

2. Install GR-MCP

git clone https://github.com/dollarhyde/gr-mcp.git
cd gr-mcp
pip install -r requirements.txt

3. Verify Installation

python -c "from gnuradio.grc.core.platform import Platform; print('GNU Radio OK')"
python -c "from mcp.server.fastmcp import FastMCP; print('MCP SDK OK')"

Usage

Client Configuration

Claude Code

Register the MCP server with Claude Code:

claude mcp add gr-mcp python /path/to/gr-mcp/src/bridge_mcp_gnuradio.py

This will automatically add the server configuration to .claude/settings.json in your project or home directory.

Codex

Register the MCP server with Codex:

codex mcp add gr-mcp python /path/to/gr-mcp/src/bridge_mcp_gnuradio.py

This will automatically add the server configuration to ~/.codex/config.toml.

Other MCP Clients

Start the server with SSE transport and point your client at the endpoint:

python src/bridge_mcp_gnuradio.py --transport sse --port 8000
# Connect your client to http://localhost:8000/mcp

Examples

Interactive hardware detection and setup

GR-MCP detects connected SDR hardware. When used with an AI assistant, the workflow becomes conversational, the LLM calls the MCP tools and guides you through configuration interactively.

User: detect sdr

┌─ detect_sdr_hardware(rescan=true) ────────────────────────────┐
│ status: devices_found                                         │
│ count: 3                                                      │
└───────────────────────────────────────────────────────────────┘

AI Assistant: Found 3 devices via UHD:

  ┌───────┬──────────┬──────────┬──────────┐
  │ Index │   Type   │ Product  │  Serial  │
  ├───────┼──────────┼──────────┼──────────┤
  │ 0     │ unknown  │ —        │ —        │
  │ 1     │ unknown  │ —        │ —        │
  │ 2     │ B200mini │ B200mini │ XXXXXXX  │
  └───────┴──────────┴──────────┴──────────┘

  The USRP B200mini (index 2) is clearly identified.
  Would you like me to set up the B200mini for use?

User: Yes

AI Assistant prompts interactively:

  Which antenna port?
  ❯ 1. TX/RX    (Recommended)
    2. RX2

  What sample rate?
  ❯ 1. 2 MHz    (good general purpose)
    2. 10 MHz   (wider bandwidth)
    3. 20 MHz   (wideband capture)
    4. 56 MHz   (maximum bandwidth)

┌─ setup_hardware(...) ─────────────────────────────────────────┐
│ device_type: "b200"                                           │
│ device_args: "serial=XXXXXXX"                                 │
│ antenna: "TX/RX", sample_rate: 20000000, gain: 40             │
└───────────────────────────────────────────────────────────────┘

AI Assistant: B200mini configured and ready:

  • Device: USRP B200mini (serial=XXXXXXX)
  • Antenna: TX/RX
  • Sample Rate: 20 MHz
  • Gain: 40 dB
  • Frequency Range: 70 MHz – 6 GHz

  Ready to build flowgraphs. What would you like to do next?
  (e.g., spectrum analyzer, FM receiver, custom signal chain)

Using a template

Templates provide pre-built flowgraphs for common applications. Parameters use ${param} substitution.

User: Create an FM receiver for 98.1 MHz

┌─ instantiate_template(...) ───────────────────────────────────┐
│ template_id: "fm_receiver"                                    │
│ params: {"center_freq":"98.1e6","samp_rate":"20000000"}       │
│ flowgraph_name: "FM Receiver 98.1 MHz"                        │
└───────────────────────────────────────────────────────────────┘

AI Assistant: FM receiver created. Let me save it to a file.

┌─ save_flowgraph(...) ─────────────────────────────────────────┐
│ filepath: "/home/user/fm_receiver_981.grc"                    │
│ flowgraph_id: "df94cb7a-1a25-48af-a951-acbb8f1e00ae"          │
└───────────────────────────────────────────────────────────────┘

AI Assistant: FM receiver flowgraph created and saved to ~/fm_receiver_981.grc:

  - Center freq: 98.1 MHz
  - Source: USRP B200mini (serial=XXXXXXX), antenna TX/RX
  - RF gain: 40 dB
  - Sample rate: 4.8 MHz (template-recommended for FM demodulation chain)
  - Audio rate: 48 kHz
  - Volume: 0.5
  - Blocks: 12 blocks, 5 connections

  To run it:
  gnuradio-companion ~/fm_receiver_981.grc

Figure 1: FM receiver flowgraph generated from the template and opened in GNU Radio Companion.

Building a flowgraph from scratch

Create a flowgraph, add blocks, connect them, validate, and save. The LLM searches the block database, configures parameters, and wires everything together. Saving auto-organizes the block layout.

User: Build a flowgraph that generates a 1 kHz sine wave at 32 kHz sample rate 
      and displays it on a time sink, frequency sink, and waterfall

┌─ list_templates() ────────────────────────────────────────────┐
│ fm_receiver, spectrum_analyzer, bpsk_transceiver              │
└───────────────────────────────────────────────────────────────┘

AI Assistant: No matching template.

┌─ create_flowgraph(...) ───────────────────────────────────────┐
│ name: "1kHz Sine Displays"                                    │
└───────────────────────────────────────────────────────────────┘

┌─ search_blocks("time sink") ──────────────────────────────────┐
│ qtgui_time_sink_x                                             │
├─ search_blocks("frequency sink") ─────────────────────────────┤
│ qtgui_freq_sink_x                                             │
├─ search_blocks("waterfall sink") ─────────────────────────────┤
│ qtgui_waterfall_sink_x                                        │
└───────────────────────────────────────────────────────────────┘

┌─ add_block(...) ──────────────────────────────────────────────┐
│ block_id: "analog_sig_source_x"                               │
│ instance_name: "sig_source"                                   │
│ params: {"type":"float", "samp_rate":"32000",                 │
│          "freq":"1000", "waveform":"analog.GR_SIN_WAVE",      │
│          "amp":"1.0"}                                         │
└───────────────────────────────────────────────────────────────┘

┌─ add_block(...) ──────────────────────────────────────────────┐
│ block_id: "qtgui_time_sink_x"                                 │
│ instance_name: "time_sink"                                    │
│ params: {"type":"float", "name":"\"Time Domain\"",            │
│          "nconnections":"1"}                                  │
│          "nconnections":"1"}                                  │
│ set_parameter: srate = 32000                                  │
│ set_parameter: size  = 1024                                   │
└───────────────────────────────────────────────────────────────┘

┌─ add_block(...) ──────────────────────────────────────────────┐
│ block_id: "qtgui_freq_sink_x"                                 │
│ instance_name: "freq_sink"                                    │
│ params: {"type":"float", "name":"\"Frequency Domain\"",       │
│          "nconnections":"1"}                                  │
│ set_parameter: bw = 32000                                     │
└───────────────────────────────────────────────────────────────┘

┌─ add_block(...) ──────────────────────────────────────────────┐
│ block_id: "qtgui_waterfall_sink_x"                            │
│ instance_name: "waterfall_sink"                               │
│ params: {"type":"float", "name":"\"Waterfall\"",              │
│          "nconnections":"1"}                                  │
│ set_parameter: bw = 32000                                     │
└───────────────────────────────────────────────────────────────┘

AI Assistant: Now connect the signal source to all three sinks:

┌─ connect_blocks(...) ─────────────────────────────────────────┐
│ "sig_source" : 0 → "time_sink" : 0                            │
│ "sig_source" : 0 → "freq_sink" : 0                            │
│ "sig_source" : 0 → "waterfall_sink" : 0                       │
└───────────────────────────────────────────────────────────────┘

┌─ validate_flowgraph() ────────────────────────────────────────┐
│ valid: true                                                   │
│ errors: []                                                    │
└───────────────────────────────────────────────────────────────┘

┌─ save_flowgraph(...) ─────────────────────────────────────────┐
│ filepath: "/home/user/sine_displays.grc"                      │
└───────────────────────────────────────────────────────────────┘

AI assistant: Flowgraph saved to ~/sine_displays.grc:

  - Signal Source: 1 kHz sine wave, float, 32 kHz sample rate, amplitude 1.0
  - QT GUI Time Sink: 1024 points, 32 kHz
  - QT GUI Frequency Sink: 1024 FFT, 32 kHz bandwidth
  - QT GUI Waterfall Sink: 1024 FFT, 32 kHz bandwidth
  - Connections: sig_source → time_sink, sig_source → freq_sink,
                 sig_source → waterfall_sink
  - Validation: passed

  To run:
  gnuradio-companion ~/sine_displays.grc

Figure 2: 1 kHz sine wave flowgraph built from scratch and opened in GNU Radio Companion.

Available Tools

The server registers tools across several categories. Use get_capabilities() for a full listing at runtime.

Hardware Detection

Tool	Description
detect_sdr_hardware	Auto-detect connected SDR devices (UHD, SoapySDR, HackRF, RTL-SDR)
get_setup_questions	Get device-specific configuration questions for a detected SDR
setup_hardware	Configure SDR hardware for the session
get_hardware_status	Get current hardware configuration

Discovery

Tool	Description
list_blocks	List available GNU Radio blocks with optional category/search filter
get_block_info	Get detailed info about a block including parameters and ports
search_blocks	Search blocks by name, label, or description
list_block_categories	List all block categories

System

Tool	Description
get_system_info	Get GNU Radio version, available modules, and diagnostics
get_capabilities	List all server capabilities and tools

Flowgraph Management

Tool	Description
create_flowgraph	Create a new empty flowgraph
load_flowgraph	Load a flowgraph from a .grc file
save_flowgraph	Save flowgraph to a .grc file (auto-organizes layout by default)
get_flowgraph_structure	Get complete flowgraph structure (blocks, connections, variables)
list_flowgraphs	List all managed flowgraphs
set_active_flowgraph	Set the active flowgraph for operations

Block and Connection Operations

Tool	Description
add_block	Add a block to the flowgraph
remove_block	Remove a block from the flowgraph
set_parameter	Set a parameter value (supports expressions)
connect_blocks	Connect two blocks
disconnect_blocks	Disconnect two blocks
check_connection_compatibility	Pre-validate port type compatibility before connecting

Validation and Code Generation

Tool	Description
validate_flowgraph	Validate flowgraph for errors
generate_python_code	Generate executable Python code

Layout

Tool	Description
organize_flowgraph_layout	Auto-arrange blocks in a .grc file following signal flow

Filter Design

Tool	Description
get_filter_info	Get info about filter types, parameters, and typical values
design_filter	Design a filter and get tap coefficients

RF Reference

Tool	Description
lookup_frequency_band	Look up frequency band allocations and parameters
get_modulation_info	Get modulation scheme parameters and recommended GNU Radio blocks
get_flowgraph_reference	Get reference block chains for common SDR applications
get_block_recipe	Get full YAML recipe for a block (make templates, callbacks, etc.)

Templates

Tool	Description
list_templates	List available flowgraph templates
instantiate_template	Create flowgraph from template with parameter substitution

Hierarchical Blocks

Tool	Description
create_hier_block	Generate hierarchical block code
export_hier_block	Export hier block to Python file

Diagnostics

Tool	Description
diagnose_flowgraph	Diagnose flowgraph issues
explain_error	Explain error messages
suggest_parameters	Get parameter suggestions based on constraints

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.