SDR MCP Server

Conversational AI control for Software Defined Radio via the Model Context Protocol.

Control RTL-SDR hardware through natural dialogue — query spectrum, tune frequencies, browse station databases, and visualize real-time waterfall displays. Works with Claude Desktop, any MCP client, or the included web dashboard.

Quick Start

# Install
pip install sdr-mcp

# Check hardware
sdr-mcp check

# Start server (STDIO mode for Claude Desktop)
sdr-mcp serve

For the web dashboard:

cd web_sota
npm install
npm run dev

Documentation

Features

Hardware Control

• Auto-detect RTL-SDR devices, initialize and configure
• Set frequency (24 MHz — 1.766 GHz), gain (auto or manual)
• Real-time IQ sample capture and spectrum processing

Spectrum Analysis

• 2048-point FFT with Hamming window
• Peak detection and signal strength analysis
• Waterfall history (100 lines) for time-varying signals

Frequency Database

• 11 pre-loaded stations across LW/MW/SW/VHF bands
• Program schedules with current-playing info
• Online search via radio-browser.info (25k+ stations)

WebSocket Streaming

• Real-time spectrum broadcast to web clients
• Remote frequency/gain control via WebSocket commands
• Canvas-based spectrum and waterfall visualizations

Web Dashboard

• Spectrum Analyzer — live FFT plot with frequency/gain controls
• Waterfall Display — color-coded time-frequency visualization
• Station Browser — search, favorites, band filters
• Online DB — query radio-browser.info by name/country/genre
• Signal ID — lookup signal types on SigID Wiki

Hardware

Recommended: RTL-SDR Blog v4 (~$35)

• 24 MHz — 1.766 GHz continuous coverage
• 0.5 ppm TCXO for frequency stability
• SMA connector, aluminum enclosure, bias tee

Any RTL2832U-based SDR with R820T2 tuner works. See RTL_SDR_V4.md for full specs.

Project Structure

sdr-mcp/
├── README.md              # This file
├── docs/                  # Documentation
│   ├── INSTALL.md         # Setup guide
│   ├── ARCHITECTURE.md    # System design
│   ├── MCP_SERVER.md      # Tool reference
│   ├── SDR_TECHNOLOGY.md  # Radio primer
│   └── RTL_SDR_V4.md      # Hardware specs
├── pyproject.toml         # Python package config
├── justfile               # Lint, fix, security recipes
├── start.ps1              # Launch backend + webapp
├── src/sdr_mcp/           # Python backend
│   ├── server.py          # FastMCP server, 17 tools
│   ├── capture.py         # RTL-SDR hardware interface
│   ├── processor.py       # FFT / spectrum processing
│   ├── frequency_db.py    # Station database
│   ├── online_db.py       # radio-browser.info API
│   ├── websocket_server.py # Real-time WebSocket stream
│   ├── transport.py       # STDIO / HTTP transport
│   └── cli.py             # Command-line interface
├── web_sota/              # React/TypeScript webapp
│   └── src/
│       ├── pages/         # Spectrum, Waterfall, Stations, etc.
│       └── components/    # Layout, UI components
└── tests/                 # Pytest test suite

Tech Stack

License

MIT