# 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)

```bash
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:

```bash
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

```bash
# After setup, run with:
uv run mcbladerf

# Or via make:
make run
```

## Usage with Claude Code

```bash
# 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:
```bash
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