Gnuradio

What is GR-MCP?

GR-MCP is a modern, extensible Machine Control Protocol (MCP) server specifically designed for GNU Radio. It enables programmatic, automated, and AI-driven creation and modification of GNU Radio flowgraphs (.grc files). This server facilitates seamless integration with Large Language Models (LLMs), automation frameworks, and custom clients, allowing users to control Software Defined Radio (SDR) workflows at scale.

How to use GR-MCP?

To use GR-MCP, you need Python 3.13+ and GNU Radio (tested with v3.10.12.0). Follow these steps:

1. Clone the repository: git clone https://github.com/yoelbassin/gr-mcp
2. Install GNU Radio: Ensure GNU Radio is installed on your system.
3. Set up a UV environment: Navigate to the gr-mcp directory and run uv venv --system-site-packages. The --system-site-packages flag is crucial as GNU Radio installs its Python package globally.
4. Configure MCP server: Add the GR-MCP server configuration to your client application (e.g., Claude Desktop or Cursor) by defining the mcpServers entry in your client's JSON configuration. An example configuration is provided in the project's README.

Key Features of GR-MCP

• MCP API: Exposes a robust Machine Control Protocol interface tailored for GNU Radio.
• Programmatic Flowgraph Creation: Allows users to build, edit, and save .grc files programmatically from code or automation scripts.
• LLM & Automation Ready: Specifically designed for easy integration with AI models and various automation frameworks.
• Extensible: Features a modular architecture that supports easy extension and customization to fit diverse needs.
• Example Flowgraphs: Includes ready-to-use .grc examples in the misc/ directory to help users get started quickly.
• Tested: Comprehensive unit tests are provided, ensuring reliability and stability.

Use Cases of GR-MCP

• Automate SDR Workflows: Streamline and automate complex Software Defined Radio operations.
• Flowgraph Generation: Programmatically generate and manage GNU Radio flowgraphs, reducing manual effort.
• AI Integration: Integrate with LLMs, bots, and other custom AI tools to enable intelligent control and creation of SDR projects.
• Rapid Prototyping: Accelerate SDR prototyping by programmatically building, modifying, and validating flowgraphs, minimizing errors.
• Scalable SDR Operations: Control and manage SDR workflows at scale, suitable for large-scale deployments or research.

FAQ from GR-MCP

Q: Why use GR-MCP? A: GR-MCP helps automate SDR workflows and flowgraph generation, integrates with LLMs and custom tools, allows programmatic building, modification, and validation of flowgraphs, and saves time by reducing manual errors in SDR prototyping.

Q: What are the requirements for GR-MCP? A: You need Python >= 3.13, GNU Radio (tested with v3.10.12.0), and UV (a Python package installer and resolver).

Q: Is GR-MCP actively developed? A: Yes, GR-MCP is in active development. Core server functionality is available, and the API and features are continuously evolving. Feedback and contributions are highly valued.

GR-MCP: A gnuradio MCP Server

GNURadio MCP Server is a modern, extensible Machine Control Protocol (MCP) server for GNURadio, enabling programmatic, automated, and AI-driven creation of GNURadio flowgraphs. Designed for seamless integration with Large Language Models (LLMs), automation frameworks, and custom clients, it empowers you to generate .grc files and control SDR workflows at scale.

Why GNURadio MCP Server?

• Automate SDR workflows and flowgraph generation
• Integrate with LLMs, bots, and custom tools
• Build, modify, and validate flowgraphs programmatically
• Save time and reduce manual errors in SDR prototyping

Features

• 🌐 MCP API: Exposes a robust MCP interface for GNURadio
• 🛠️ Programmatic Flowgraph Creation: Build, edit, and save .grc files from code or automation
• 🤖 LLM & Automation Ready: Designed for AI and automation integration
• 🧩 Extensible: Modular architecture for easy extension and customization
• 📝 Example Flowgraphs: Includes ready-to-use .grc examples in the misc/ directory
• 🧪 Tested: Comprehensive unit tests with pytest

Quickstart

Requirements

• Python >= 3.13
• GNURadio (Tested with GNURadio Companion v3.10.12.0)
• UV

Usage

1. Clone the repository

git clone https://github.com/yoelbassin/gr-mcp

2. Install GNURadio

3. Set up a UV environment

cd gr-mcp
uv venv --system-site-packages

The --system-site-packages flag is required because GNURadio installs the gnuradio Python package globally.

4. Add the MCP server configuration to your client configuration. For example, for Claude Desktop or Cursor:

"mcpServers": {
    "gr-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gr-mcp",
        "run",
        "main.py"
      ]
    }
  }

Development

Install development dependencies and run tests with:

pip install -e ".[dev]"
pytest

Project Status

In active development. Core server functionality is available, but the API and features are evolving. Your feedback and contributions are highly valued!