Installation

GR-MCP requires Python 3.14+, GNU Radio with GRC, and optionally Docker for runtime control features.

Prerequisites

# GNU Radio and GRC
sudo pacman -S gnuradio gnuradio-companion

# UV package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Docker (optional, for runtime control)
sudo pacman -S docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# GNU Radio and GRC
sudo apt install gnuradio gnuradio-dev

# UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Docker (optional)
sudo apt install docker.io docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# GNU Radio and GRC
sudo dnf install gnuradio gnuradio-devel

# UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Docker (optional)
sudo dnf install docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Install GR-MCP

Clone the repository

git clone https://git.supported.systems/MCP/gr-mcp
cd gr-mcp

Create a virtual environment with system site-packages

The --system-site-packages flag is required because GNU Radio’s Python bindings are installed system-wide and must be accessible within the virtual environment.
Terminal window
```
uv venv --system-site-packages --python 3.14
```
Install dependencies
Terminal window
```
uv sync
```
Verify the installation
Terminal window
```
uv run gnuradio-mcp
```
You should see the FastMCP server start. Press Ctrl+C to stop.

Configure Your MCP Client

Add GR-MCP to your MCP client configuration:

Edit ~/.config/claude/claude_desktop_config.json:

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

claude mcp add gr-mcp -- uv --directory /path/to/gr-mcp run gnuradio-mcp

Or add to your project’s .mcp.json:

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

Edit your Cursor settings or .cursor/mcp.json:

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

Build Docker Images (Optional)

For runtime control features (launching flowgraphs in containers, visual feedback, code coverage):

cd gr-mcp

# Base runtime image with Xvfb + VNC + ImageMagick
docker build -f docker/Dockerfile.gnuradio-runtime \
  -t gnuradio-runtime:latest docker/

# Coverage image (adds python3-coverage)
docker build -f docker/Dockerfile.gnuradio-coverage \
  -t gnuradio-coverage:latest docker/

Next Steps

Now that GR-MCP is installed, try:

Build your first flowgraph — Create and validate a complete signal chain
Running in Docker — Launch flowgraphs with runtime control