Gnuradio Server

PyPI version Python Versions License: MIT

An MCP (Model Context Protocol) server that bridges an LLM to a live GNU Radio SDR flowgraph. Control your software-defined radio — tune frequencies, adjust gain, capture IQ samples, analyse spectra, and sweep for signals — all through natural language via any MCP-compatible client.

Architecture

┌─────────────┐      MCP (stdio / HTTP)      ┌──────────────────┐
│   LLM /     │◄──────────────────────────────►│  gnuradio_mcp    │
│   Claude    │        tool calls &            │  MCP Server      │
│   Desktop   │        responses               │                  │
└─────────────┘                                └──┬──────────┬───┘
                                                  │          │
                                    XML-RPC       │          │  ZMQ SUB
                                    (control)     │          │  (IQ data)
                                                  ▼          ▼
                                            ┌────────────────────┐
                                            │    GNU Radio       │
                                            │    Companion       │
                                            │    Flowgraph       │
                                            │  ┌──────────────┐  │
                                            │  │ XMLRPC Server │  │
                                            │  │ ZMQ PUB Sink  │  │
                                            │  └──────────────┘  │
                                            └────────┬───────────┘
                                                     │
                                                     ▼
                                            ┌────────────────────┐
                                            │  SDR Hardware      │
                                            │  (HackRF / RTL-SDR │
                                            │   / USRP / Sim)    │
                                            └────────────────────┘

Quick Start (Simulation — No Hardware)

pip install gnuradio-mcp-server

# Open simulation_mcp.grc in GNU Radio Companion and click Run
# (provides two test tones at +10 kHz and +50 kHz from center)

gnuradio-mcp

Quick Start (HackRF)

pip install gnuradio-mcp-server

# Open hackrf_mcp.grc in GNU Radio Companion and click Run & ensure HackRF is connected

GNURADIO_HARDWARE=hackrf gnuradio-mcp

Claude Desktop Integration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "gnuradio_mcp": {
      "command": "gnuradio-mcp",
      "args": [],
      "env": {
        "GNURADIO_HARDWARE": "hackrf",
        "GNURADIO_GR_HOST": "127.0.0.1",
        "GNURADIO_GR_XMLRPC_PORT": "8080",
        "GNURADIO_GR_ZMQ_PORT": "5555"
      }
    }
  }
}

For HTTP transport:

{
  "mcpServers": {
    "gnuradio_mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "streamable-http"
    }
  }
}

Tools Reference

Environment Variables

All variables use the GNURADIO_ prefix:

Edge Cases & Known Limitations

1. Sample rate restart: Some SDR hardware (especially RTL-SDR) requires a flowgraph restart after changing the sample rate. The gnuradio_set_sample_rate tool includes a warning about this.

2. ZMQ dtype requirement: The ZMQ PUB Sink in your flowgraph must output complex64 (8 bytes per sample). Misaligned data will raise a GRHardwareError.

3. Frequency clamping: Frequencies outside the configured [freq_min_hz, freq_max_hz] range are rejected before being sent to hardware. Adjust the env vars for your specific hardware.

4. Context overflow warning: Capturing more than 65,536 IQ samples triggers a warning, as the response summary may still be large. Use gnuradio_get_spectrum_snapshot for analysed results instead.

5. XML-RPC not thread-safe: A new ServerProxy is created per RPC call to avoid shared-state bugs in async contexts.

6. ZMQ socket lifecycle: Each recv_samples call opens and closes its own ZMQ SUB socket. This is intentional — the slight overhead avoids shared-socket state issues.

Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with HTTP transport
GNURADIO_TRANSPORT=streamable_http python -m gnuradio_mcp.server

License

MIT