Natural language-driven creation and management of GNU Radio flowgraphs.
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"
Tools (2)
detect_sdr_hardwareDetects connected SDR hardware and returns device information.setup_hardwareConfigures the detected SDR hardware for use in a flowgraph.Configuration
{"mcpServers": {"gr-mcp": {"command": "python", "args": ["/path/to/gr-mcp/src/bridge_mcp_gnuradio.py"]}}}