SpectraMCP

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.

// Add directly to claude_desktop_config.json
{
  "mcpServers": {
    "spectramcp": {
      "command": "uvx",
      "args": ["spectramcp"]
    }
  }
}

📖 Table of Contents

• What is SpectraMCP?

• Key Features

• System Architecture

• Mathematical & Technical Formulation

• Setup & Installation

• Connecting to AI Clients

• How to Use

• Reference Tables

• Benchmarks & Comparisons

• Scope & Limitations

• File Structure

• Troubleshooting

• Contributing & Security

• Deployment & GitHub Releases

• License

Related MCP server: SDR MCP Server

💡 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.

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;

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

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)

git clone https://github.com/IamOumarIbrahim/SpectraMCP.git
cd SpectraMCP
pip install -e .

🔍 Verification Command:

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:

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

   {
     "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

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.

⚖️ Benchmarks & Comparisons

🔬 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

🧩 Contributing & Security

• Contributing: Please review CONTRIBUTING.md for development setup and PR guidelines.

• Code of Conduct: Adheres to the Contributor Covenant. See CODE_OF_CONDUCT.md.

• Security Policy: For vulnerability reporting, see 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:

git tag v1.0.0
git push origin v1.0.0

See .github/workflows/release.yml for workflow details.

📄 License

MIT © 2026 Oumar Ibrahim

🙏 Powered By

NumPy · SciPy · SoapySDR · sigmf-python · FastMCP

If SpectraMCP saved you from writing another one-off FFT script, a ⭐ helps other people find it.