GNU Radio MCP Server for Autonomous LLM Flowcharts

Overview

This MCP (Model Context Protocol) server integrates GNU Radio Companion (GRC) flowchart manipulation into an LLM-driven toolchain. It exposes programmatic operations for creating, reading, modifying, validating, and rendering .grc flowchart files so language models or agents can autonomously generate RF prototypes, iterate on designs, and produce artifacts for simulation or deployment.

The server is useful for rapid prototyping and automated experimentation workflows where an LLM acts as a design assistant. Instead of manually editing XML-based .grc files, the LLM can call well-defined MCP tools to add blocks, tune parameters, connect ports, validate structure, and generate visual previews—significantly shortening the design iteration loop for radio-frequency applications.

Features

• Exposes MCP-compatible tool endpoints to manipulate GNU Radio .grc files
• Create, read, update, and delete flowcharts (CRUD for .grc projects)
• XML-based block and connection editing (add/remove blocks, set params)
• Validation of GRC syntax and basic semantic checks
• Render flowchart previews (PNG/SVG) for quick visual feedback
• File management for projects and artifacts (downloadable .grc and rendered images)
• Configurable working directory and integration points for GNU Radio versions

Installation / Configuration

Clone and set up the server locally, then run it with a Python ASGI server such as uvicorn.

# clone the repo
git clone https://github.com/yoelbassin/gnuradioMCP.git
cd gnuradioMCP

# create and activate virtualenv (Unix/macOS)
python3 -m venv .venv
source .venv/bin/activate

# install Python dependencies
pip install -r requirements.txt

# run the MCP server (example)
uvicorn mcp_server:app --host 0.0.0.0 --port 8000

Environment variables and configuration options:

Set environment variables before starting the server:

export WORK_DIR=/var/gnuradio_projects
export GRC_PATH=/usr/bin/grcc
export MCP_PORT=8000

Notes:

• Ensure GNU Radio is installed and the GRC tools (grcc, python-gnuradio bindings) are available if you plan to render/validate flowcharts.
• Server should be run with appropriate file permissions for the working directory.

Available Tools / Resources

The server provides a collection of MCP-accessible tools designed to be called by LLMs or agent frameworks. Example tool categories:

• project.create — create a new .grc project folder and skeleton .grc file
• project.list / project.delete — list or remove projects
• flowchart.read — return .grc XML or a summarized JSON representation
• flowchart.write — apply modifications to blocks, parameters, or connections
• block.catalog — list available GNU Radio blocks and their parameters
• validator.run — run syntactic/semantic checks on a .grc file
• render.preview — generate a visual preview (PNG/SVG) of the flowchart
• artifact.download — fetch generated files (GRC, images, logs)

Example minimal MCP request (JSON) for creating a flowchart:

{
  "tool": "flowchart.write",
  "input": {
    "project": "example_rx",
    "operation": "create",
    "blocks": [
      {"id": "src", "type": "osmosdr_source", "params": {"freq": 915e6, "gain": 20}},
      {"id": "throttle", "type": "blocks_throttle", "params": {"sample_rate": 1e6}}
    ],
    "connections": [
      {"from": "src:0", "to": "throttle:0"}
    ]
  }
}

Use Cases

• Rapid prototyping: An LLM generates a receiver flowgraph for a target frequency, validates it, and produces a visual preview for review—without manual GRC editing.
• Parameter sweeps: Automate creation of multiple .grc variants where an agent adjusts block parameters (e.g., different filter cutoffs or sample rates) and collects results.
• Educational assistants: Students describe a radio chain in natural language and the LLM constructs a corresponding .grc file the instructor can inspect and run.
• Automated testing: CI pipelines generate test flowcharts to exercise different GNU Radio blocks, run validators, and archive artifacts.
• Collaborative design: Multiple LLM agents operate on a shared project workspace to propose and apply incremental changes; the server provides atomic operations and validation to keep projects consistent.

Tips for Developers

• Treat the server as a tool-provider for your LLM agent: implement idempotency and conflict resolution in your agent when multiple write operations are possible.
• Use render.preview for quick human verification before deploying or running generated flowgraphs.
• Maintain a versioned working directory to enable rollbacks when an automated modification produces unexpected results.

For full code, implementation details, and issues, see the repository: https://github.com/yoelbassin/gnuradioMCP