GR-MCP Server

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"