SpectraMCP
README.md
<div align="center">
<h1>🛰️ SpectraMCP</h1>
<p><strong>The Model Context Protocol Server for RF Signal Processing, SDR & Radar DSP</strong></p>
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/IamOumarIbrahim/SpectraMCP/actions/workflows/ci.yml)
[](https://modelcontextprotocol.io/)
<br />
[](https://www.rtl-sdr.com/)
[](https://greatscottgadgets.com/hackrf/)
[](https://github.com/pothosware/SoapySDR)
</div>
<p align="center">
<img src="assets/demo.gif" alt="SpectraMCP Live Waterfall Demo" width="100%" />
</p>
> [!IMPORTANT]
> **Hardware Optional**: SpectraMCP runs fully in file-based mode (`.wav`, `.iq`, `.sigmf-data`, `.npy` radar cubes) with zero hardware. If an RTL-SDR, HackRF, or any SoapySDR-supported device is attached, live-capture tools unlock automatically.
**SpectraMCP** is a zero-trust Model Context Protocol (MCP) server that gives AI agents (Claude Desktop, Claude Code, Cursor, Antigravity) native tool access to RF spectrum capture, spectral analysis, and classical radar-DSP primitives — no SDR hardware required to get started.
```json
// Add directly to claude_desktop_config.json
{
"mcpServers": {
"spectramcp": {
"command": "uvx",
"args": ["spectramcp"]
}
}
}
```
<br />
> [!TIP]
> **GitHub About Section**: *🛰️ The Model Context Protocol Server for RF Signal Processing, SDR & Radar DSP — We're totally on the same wavelength! 📶*
>
> **Repository Topics / Tags**: `mcp` · `sdr` · `radar-dsp` · `rf-signals` · `fft` · `cfar` · `mvdr` · `kalman-filter` · `spectrogram` · `sigmf` · `rtl-sdr` · `hackrf` · `soapysdr` · `fastmcp` · `python`
---
## 📖 Table of Contents
- [What is SpectraMCP?](#-what-is-spectramcp)
- [Key Features](#-key-features)
- [System Architecture](#-system-architecture)
- [Mathematical & Technical Formulation](#-mathematical--technical-formulation)
- [Setup & Installation](#-setup--installation)
- [Connecting to AI Clients](#-connecting-to-ai-clients)
- [How to Use](#-how-to-use)
- [Reference Tables](#-reference-tables)
- [Benchmarks & Comparisons](#-benchmarks--comparisons)
- [Scope & Limitations](#-scope--limitations)
- [File Structure](#-file-structure)
- [Troubleshooting](#-troubleshooting)
- [Contributing & Security](#-contributing--security)
- [Deployment & GitHub Releases](#-deployment--github-releases)
- [License](#-license)
---
## 💡 What is SpectraMCP?
Every AI coding agent can *write* a DSP script. None of them can *see* a spectrum. Today, working with RF signals alongside an AI agent means a constant context-switch: the agent writes a `matplotlib` script, you run it, you screenshot the plot back into the chat, and you describe what you're looking at in words. SpectraMCP removes that loop entirely.
Instead of maintaining a folder of one-off analysis scripts, SpectraMCP unifies RF and radar DSP behind a single, structured tool interface:
- **Spectral Analysis**: FFTs, STFT spectrograms, and rolling PSD waterfalls rendered directly as images the agent can reason over.
- **Radar DSP Primitives**: 2D Range-Doppler processing, CA-CFAR detection, MVDR/Capon beamforming, and Kalman-filter multi-target tracking — exposed as callable tools instead of standalone scripts.
- **Signal Classification**: Rule-based modulation and micro-Doppler cadence classification for quick "what am I looking at" triage.
- **Hardware Bridge**: Optional live capture from RTL-SDR, HackRF, and any SoapySDR-supported device.
---
## ✨ Key Features
- 📡 **Signal I/O & Format Parser**: Loads `.wav`, raw `.iq`, `.sigmf-data/.sigmf-meta`, and `.npy` radar cubes into a normalized, zero-copy `IQBuffer`.
- 📊 **Spectral Analysis Engine**: Windowed FFTs (Hann/Hamming/Blackman), high-resolution STFT spectrograms, and rolling PSD waterfall visualization.
- 🎯 **Radar DSP Suite**: 2D FMCW Range-Doppler processing, 2D CA-CFAR adaptive thresholding, MVDR/Capon beamforming with diagonal loading, and constant-velocity Kalman multi-target tracking.
- 🔍 **Signal & Micro-Doppler Classifier**: Feature-based modulation scheme identification (AM/FM/OOK/FSK/PSK) and cadence-spectrum periodicity extraction for rotor-vs-flutter discrimination.
- 📁 **Local Workspace Export**: Saves generated plots and sliced IQ data segments directly to a user-configured local directory via `SPECTRAMCP_WORKSPACE`.
---
## ⚙️ System Architecture
SpectraMCP unifies file loaders, SDR hardware bridges, spectral rendering, radar processing, and classification engines behind the stdio FastMCP transport layer.
```mermaid
graph TD
Agent["AI Agent (Claude / Cursor / Antigravity)"] --> Server["SpectraMCP stdio Server"]
Server --> IO[Signal I/O Layer]
IO --> File["File Loaders: .wav / .iq / .sigmf / .npy"]
IO --> HW["SDR Bridge: RTL-SDR / HackRF / SoapySDR"]
Server --> Spectral[Spectral Analysis Engine]
Spectral --> FFT["Windowed FFT"]
Spectral --> STFT["STFT Spectrogram"]
Spectral --> Waterfall["Rolling PSD Waterfall"]
Server --> Radar[Radar DSP Engine]
Radar --> RDM["2D Range-Doppler Map"]
Radar --> CFAR["2D CA-CFAR Detector"]
Radar --> Beam["MVDR / Capon Beamformer"]
Radar --> Track["Kalman Multi-Target Tracker"]
Server --> Classify[Classification Engine]
Classify --> Mod["Modulation Classifier"]
Classify --> MicroD["Micro-Doppler Cadence Extractor"]
Server --> Workspace["Workspace Export"]
Workspace --> Out["PNG / GIF / .npy / .sigmf Output"]
classDef default fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
classDef process fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
class Spectral,Radar,Classify process;
```
> [!NOTE]
> **Zero-Trust & Stdio Isolation**: SpectraMCP communicates strictly via standard I/O streams (`stdio`). It opens no network ports and requires no elevated privileges.
---
## 📐 Mathematical & Technical Formulation
### 1. FMCW Beat Frequency Model
For any supplied `RadarCube`, range-to-beat-frequency mapping follows the standard closed-form FMCW relation. For a target at range $R$, sweep bandwidth $B$, and chirp duration $T_c$:
$$f_b = \frac{2BR}{cT_c} \implies R = \frac{f_b c T_c}{2B}$$
`range_doppler_map` applies Blackman windowing across both fast-time and slow-time axes before 2D FFT computation to suppress sidelobe leakage.
### 2. 2D CA-CFAR Threshold
`ca_cfar_detect` estimates the local noise floor $P_n$ by averaging training cells around the cell-under-test (CUT), excluding guard cells, then applies:
$$T_{cell} = \alpha \cdot P_n, \qquad \alpha = N_{ref}\left(P_{fa}^{-1/N_{ref}} - 1\right)$$
where $N_{ref}$ is the number of reference training cells and $P_{fa}$ is the user-specified target false-alarm probability (default $10^{-3}$).
### 3. MVDR Diagonal Loading
`mvdr_beamform` regularizes the sample covariance matrix $\hat{\mathbf{R}}$ whenever snapshot count $K < M$ array elements:
$$\hat{\mathbf{R}}_{loaded} = \hat{\mathbf{R}} + \epsilon \cdot \text{tr}(\hat{\mathbf{R}}) \cdot \mathbf{I}$$
$$\mathbf{w} = \frac{\hat{\mathbf{R}}_{loaded}^{-1}\mathbf{a}(\theta)}{\mathbf{a}(\theta)^H \hat{\mathbf{R}}_{loaded}^{-1}\mathbf{a}(\theta)}$$
---
## 🚀 Setup & Installation
### Option A: 1-Click Setup (Windows)
```cmd
setup.bat
```
Installs Python 3.12 via `winget` if missing, installs `spectramcp` and its Python dependencies, and auto-configures `claude_desktop_config.json` with an absolute interpreter path.
### Option B: Manual Installation (Windows / macOS / Linux)
```bash
git clone https://github.com/IamOumarIbrahim/SpectraMCP.git
cd SpectraMCP
pip install -e .
```
🔍 **Verification Command**:
```bash
python -m spectramcp.selftest
```
*Expected Output*: `[OK] Core DSP engine [OK] MCP transport [SDR: not detected — file mode only]`
### Optional: SDR Hardware Drivers
Only required if you plan to use `capture_from_sdr` / `list_sdr_devices`:
```bash
# Windows (winget)
winget install --id PothosWare.SoapySDR -e
# macOS (Homebrew)
brew install soapysdr rtl-sdr hackrf
# Linux (Debian/Ubuntu)
sudo apt install soapysdr-tools librtlsdr-dev libhackrf-dev
```
---
## 🔌 Connecting to AI Clients
### Claude Desktop
1. Open your configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add the `spectramcp` server entry:
```json
{
"mcpServers": {
"spectramcp": {
"command": "python",
"args": ["-m", "spectramcp.server"],
"env": {
"SPECTRAMCP_WORKSPACE": "C:\\Users\\YourUsername\\Downloads\\Spectra_Outputs"
}
}
}
}
```
3. Restart **Claude Desktop** and open the tool icon to confirm all 13 tools are registered.
---
## 🖥️ How to Use
```text
User: Load capture_2026_07_29.sigmf-data, show me the waterfall for the first 5 seconds,
then run CA-CFAR at Pfa=1e-3 and tell me what you find.
Agent:
→ load_iq_file(path="capture_2026_07_29.sigmf-data")
→ render_waterfall(duration_s=5.0)
[returns waterfall.png]
→ range_doppler_map(source="last_loaded")
→ ca_cfar_detect(pfa=1e-3, guard_cells=2, training_cells=12)
[returns detections at ranges 41.2m, 118.6m, 203.9m]
"The waterfall shows a steady carrier around 433.9 MHz with two brief bursts.
CFAR detected 3 targets after Range-Doppler processing — ranges and radial
velocities are annotated on the returned detection map."
```
---
## 📊 Reference Tables
*Highlights of provided tools. View complete parameters in [docs/TOOLS_REFERENCE.md](docs/TOOLS_REFERENCE.md).*
| Category | MCP Tool | Description |
| :--- | :--- | :--- |
| **Signal I/O** | `load_iq_file` | Loads `.wav`, `.iq`, `.sigmf-data/.sigmf-meta`, or `.npy` into a normalized `IQBuffer` |
| **Signal I/O** | `capture_from_sdr` | Captures a fixed-duration IQ segment from an attached RTL-SDR/HackRF/SoapySDR device |
| **Signal I/O** | `list_sdr_devices` | Enumerates attached SDR hardware and reports supported sample rates / tunable range |
| **Spectral Analysis** | `compute_fft` | Windowed FFT with configurable window (Hann/Hamming/Blackman) and zero-padding factor |
| **Spectral Analysis** | `render_spectrogram` | STFT spectrogram image with configurable frame size, hop, and dB dynamic range |
| **Spectral Analysis** | `render_waterfall` | Rolling PSD waterfall across N consecutive capture segments |
| **Radar DSP** | `range_doppler_map` | 2D windowed FFT (fast-time/slow-time) over a supplied `RadarCube` |
| **Radar DSP** | `ca_cfar_detect` | 2D Cell-Averaging CFAR detector with configurable guard/training cell geometry |
| **Radar DSP** | `mvdr_beamform` | Adaptive Capon/MVDR beamformer with diagonal-loading stabilization for rank-deficient snapshots |
| **Radar DSP** | `kalman_track` | Constant-velocity Kalman tracker associating detections across sequential frames |
| **Classification** | `classify_modulation` | Rule-based AM/FM/OOK/FSK/PSK-family classifier using envelope, kurtosis, and spectral-flatness features |
| **Classification** | `micro_doppler_signature` | Cadence-spectrum periodicity extraction for rotor-vs-flutter style signature comparison |
| **Workspace** | `export_plot` / `export_iq_segment` | Saves any generated figure or IQ slice directly to a local folder on the user's PC |
---
## ⚖️ Benchmarks & Comparisons
| Tool | Primary Purpose | Where SpectraMCP Fits |
| :--- | :--- | :--- |
| **GNU Radio** | Full flow-graph SDR runtime | SpectraMCP exposes discrete, agent-callable analysis primitives rather than a visual flow-graph builder |
| **GQRX / SDR#** | Live GUI spectrum viewer | SpectraMCP is headless; built to be driven by an AI agent reasoning over spectral images |
| **Universal Radio Hacker** | Manual protocol reverse-engineering | Complementary — URH is for interactive dissection, SpectraMCP is for agent-driven automated triage |
---
## 🔬 Scope & Limitations
- **Passive Receiver Scope**: SpectraMCP focuses exclusively on signal analysis, spectral visualization, and radar target extraction. It contains no transmission, jamming, or active protocol decoding logic.
- **Hardware Agnostic Fallback**: If physical SDR hardware is unplugged or missing drivers, live capture tools fall back cleanly to file-based mode without crashing server execution.
---
## 📁 File Structure
```
SpectraMCP/
├── spectramcp/
│ ├── server.py - FastMCP stdio server & tool registration
│ ├── io.py - File loaders and SDR hardware bridge
│ ├── spectral.py - FFT, STFT, waterfall rendering
│ ├── radar.py - Range-Doppler, CA-CFAR, MVDR, Kalman tracker
│ ├── classify.py - Modulation & micro-Doppler classifiers
│ └── selftest.py - Verification CLI module (python -m spectramcp.selftest)
├── tests/ - Pytest suite (DSP + MCP schema)
├── docs/TOOLS_REFERENCE.md - Full 13-tool parameter reference
├── .github/workflows/ - CI/CD and release automation
├── setup.bat - Windows 1-click installer
├── pyproject.toml - Package configuration
├── SECURITY.md - Security disclosure policy
├── CONTRIBUTING.md - Contribution guidelines
└── CODE_OF_CONDUCT.md - Code of conduct
```
---
## 🩹 Troubleshooting
| Issue | Root Cause | Resolution |
| :--- | :--- | :--- |
| `No SDR devices found` | Missing SoapySDR driver or unplugged hardware | Reinstall drivers per [Setup Guide](#-setup--installation); file-mode tools still work |
| `ENOENT` on Claude Desktop connect | Relative Python path in config | Use an absolute interpreter path, as shown in [Connecting to AI Clients](#-connecting-to-ai-clients) |
| CFAR returns 0 detections | `pfa` set too conservatively for signal SNR | Lower `pfa` (e.g. `1e-2`) or verify the input `RadarCube` isn't pure noise |
| `librtlsdr not found` | RTL-SDR driver not installed | Run the SoapySDR driver install step under [Setup Guide](#-setup--installation) |
---
## 🧩 Contributing & Security
- **Contributing**: Please review [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
- **Code of Conduct**: Adheres to the Contributor Covenant. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
- **Security Policy**: For vulnerability reporting, see [SECURITY.md](SECURITY.md).
---
## 🚀 Deployment & GitHub Releases
Automated releases and build artifacts are generated via GitHub Actions whenever a new release tag (e.g. `v1.0.0`) is pushed to the repository:
```bash
git tag v1.0.0
git push origin v1.0.0
```
See [.github/workflows/release.yml](.github/workflows/release.yml) for workflow details.
---
## 📄 License
MIT © 2026 [Oumar Ibrahim](https://github.com/IamOumarIbrahim)
## 🙏 Powered By
[NumPy](https://numpy.org/) · [SciPy](https://scipy.org/) · [SoapySDR](https://github.com/pothosware/SoapySDR) · [sigmf-python](https://github.com/sigmf/sigmf-python) · [FastMCP](https://github.com/jlowin/fastmcp)
<div align="center">
If SpectraMCP saved you from writing another one-off FFT script, a ⭐ helps other people find it.
</div>
TDQS
B3.3/5.0
Scored across 14 tools
Disambiguation5/5
Each tool has a clearly distinct purpose in the signal processing pipeline, from device enumeration and IQ capture to advanced radar processing and export. No two tools overlap in functionality.
Naming Consistency4/5
All tool names use lowercase with underscores and mostly follow a verb_noun pattern (e.g., load_iq_file, capture_from_sdr). A few names like range_doppler_map and micro_doppler_signature are noun-heavy, but the overall style is consistent and predictable.
Tool Count5/5
14 tools cover the essential capabilities for an SDR server without being excessive. Each tool serves a specific, non-redundant function, and the count is appropriate for the scope.
Completeness4/5
The set covers acquisition, analysis (FFT, spectrogram, waterfall, radar processing, classification, tracking), and export. While basic filtering or demodulation tools are missing, the surface is comprehensive for typical SDR and radar workflows.
Maintenance
ActivityMaintained
ResponsivenessSyncing