GR-MCP: A gnuradio MCP Server

What is GR-MCP?

GR-MCP is an LLM-driven RF tool for Claude Code. Describe what you want on the air and it surveys the spectrum, builds and runs a receiver, looks at the signal, and leaves a reproducible RF project behind — SigMF captures, YAML pipelines, and .grc flowgraphs you own. It is simulation-only (v1.0, no hardware support yet) and was previously known as GNURadio/GR-MCP.

How to use GR-MCP?

Install via Claude Code’s plugin marketplace with /plugin marketplace add yoelbassin/gr-mcp and /plugin install marconi. No further configuration is needed; uv starts the MCP server on first use. Then ask in plain language, e.g. "Simulate an FM station at 100.3 MHz and build me a receiver."

Key features of GR-MCP

• Survey‑spectrum: detect signals, PSD, spectrogram
• Simulate‑scene: register a simulated device from a description
• Build‑receiver: channelize, demodulate, validate, run, verify, save
• Debug‑no‑signal: locate faults when a receiver outputs nothing
• TX‑experiment: closed‑loop transmit‑then‑receive in simulation
• Escape‑hatch: drop to the Python library when no tool fits

Use cases of GR-MCP

• Rapid prototyping of RF receivers by describing them in natural language
• Learning signal processing by inspecting generated flowgraphs and captures
• Debugging a “no signal” scenario in a simulated environment
• Running reproducible simulation experiments with full artifact persistence

FAQ from GR-MCP

What does GR-MCP do exactly?

GR-MCP lets you describe an RF task in natural language, then it surveys the spectrum, builds a receiver, runs it, and leaves behind reproducible project files (SigMF, YAML, GNU Radio flowgraphs). Currently all operations are simulation‑only.

How do I install GR-MCP?

In Claude Code, run /plugin marketplace add yoelbassin/gr-mcp followed by /plugin install marconi. The server uses uv and requires Python ≥3.13 and GNU Radio 3.10+ installed system‑wide (conda‑forge, distro packages, or Homebrew).

Does GR-MCP work with real hardware?

No, v1.0 is simulation‑only. Check ROADMAP.md for future hardware support.

What dependencies does GR-MCP need?

You need uv, Python ≥3.13, and GNU Radio 3.10+ installed system‑wide. Analyzing existing IQ files does not require GNU Radio.

Where do GR-MCP’s results get saved?

Artifacts (captures, flowgraphs, logs) land under artifacts/ in the server’s working directory. Set the environment variable MARCONI_WORKSPACE to store them elsewhere.