mcbladerf

MCP server for Nuand BladeRF SDR control via SoapySDR.

Overview

mcbladerf provides Model Context Protocol (MCP) tools for controlling Nuand BladeRF software-defined radios. It enables AI assistants to configure RF parameters, capture IQ samples, and perform spectrum analysis through a simple tool-based interface.

Features

• Device Management: Enumerate, connect, and disconnect BladeRF devices
• RF Configuration: Set/get frequency, sample rate, bandwidth, and gain stages
• IQ Capture: Stream samples to files in CF32 or CS16 format
• Spectrum Analysis: Capture and compute FFT power spectra
• Advanced Operations: FPGA loading, firmware flashing, DC calibration

Requirements

• Python 3.14+ (must match system SoapySDR installation)
• SoapySDR with BladeRF support (system packages)
• bladeRF CLI tools (for advanced operations)
• BladeRF 1.0 or 2.0 hardware

System Dependencies (Arch Linux)

sudo pacman -S soapysdr soapysdr-bladerf bladerf

Installation

SoapySDR is a C++ library with Python bindings that must be installed system-wide. The venv needs access to system site-packages:

cd mcbladerf

# One-time setup (creates venv with system site-packages access)
make setup

# Or manually:
uv venv --system-site-packages --python 3.14
uv pip install -e .

Running

# After setup, run with:
uv run mcbladerf

# Or via make:
make run

Usage with Claude Code

# Add to Claude Code (with full path)
claude mcp add mcbladerf -- uv run --directory /path/to/mcbladerf mcbladerf

The .mcp.json is already configured for local use:

claude -p "show bladerf status" --mcp-config .mcp.json --allowedTools "mcp__mcbladerf__*"

Available Tools

Device Management

• bladerf_status - Get comprehensive device status
• bladerf_list_devices - Enumerate connected devices
• bladerf_connect - Connect to a device by serial or index
• bladerf_disconnect - Close the current connection

RF Configuration

• bladerf_get_frequency / bladerf_set_frequency - Center frequency
• bladerf_get_sample_rate / bladerf_set_sample_rate - Sample rate
• bladerf_get_bandwidth / bladerf_set_bandwidth - Analog bandwidth
• bladerf_get_gain / bladerf_set_gain - Individual gain stages
• bladerf_list_gains - Enumerate available gain stages
• bladerf_get_frequency_range / bladerf_get_sample_rate_range - Hardware limits

IQ Capture

• bladerf_capture_iq - Stream samples to file (CF32/CS16)
• bladerf_capture_spectrum - Capture and compute FFT
• bladerf_stream_status - Check capture progress
• bladerf_stop_capture - Abort running capture

Advanced

• bladerf_load_fpga - Load FPGA bitstream (RAM)
• bladerf_flash_firmware - Flash FX3 firmware
• bladerf_calibrate_dc - Run DC offset calibration
• bladerf_get_hardware_info - Detailed hardware info
• bladerf_set_loopback - Configure loopback mode
• bladerf_probe - Device diagnostics

Example Session

> Connect to my BladeRF and show status
[Uses bladerf_connect and bladerf_status]

> Set frequency to 915 MHz with 2 MHz sample rate
[Uses bladerf_set_frequency and bladerf_set_sample_rate]

> Capture 1 second of IQ data to /tmp/capture.cf32
[Uses bladerf_capture_iq]

> Show me the spectrum around 100 MHz
[Uses bladerf_capture_spectrum]

BladeRF 1.0 x40 Specifications

• Frequency: 237.5 MHz - 3.8 GHz
• Sample rates: 80 Ksps - 40 Msps
• RX Gain stages: lna (0/3/6 dB), rxvga1 (5-30 dB), rxvga2 (0-30 dB)
• TX Gain stages: txvga1 (-35 to -4 dB), txvga2 (0-25 dB)

License

MIT