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

Discovery

System

Flowgraph Management

Block and Connection Operations

Validation and Code Generation

Layout

Filter Design

RF Reference

Templates

Hierarchical Blocks

Diagnostics

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

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