Skip to content

N-Erickson/AetherLink-SDR-MCP

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
.github/workflows
.github/workflows
 
 
docker
docker
 
 
examples
examples
 
 
sdr_mcp
sdr_mcp
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
VERIFICATION.md
VERIFICATION.md
 
 
pyproject.toml
pyproject.toml
 
 
pytest.ini
pytest.ini
 
 
readme.md
readme.md
 
 

Repository files navigation

AetherLink-SDR-MCP: Software Defined Radio Model Context Protocol Server

Control Software Defined Radios and decode radio protocols through an AI-friendly Model Context Protocol interface.

🚀 Features

  • Protocol Decoders: ADS-B aircraft tracking, POCSAG pagers, AIS ship tracking, Meteor-M LRPT satellites, ISM band devices
  • Weather Satellites: Meteor-M2-3/M2-4 LRPT decoding with SatDump (NOAA APT deprecated - decommissioned Aug 2025)
  • Advanced Analysis: Real-time spectrum analysis, waterfall displays, signal detection, frequency scanning
  • Audio Recording: Demodulate and record FM/AM audio as WAV files
  • ISM Band Scanning: Decode 433MHz/315MHz devices (weather stations, sensors, doorbells, tire pressure monitors)
  • MCP Integration: Seamless integration with Claude Desktop and other MCP clients
  • 27 MCP Tools: Complete SDR control through natural language

📦 Installation

Prerequisites

1. RTL-SDR Drivers:

# macOS
brew install librtlsdr

# Ubuntu/Debian
sudo apt-get install rtl-sdr librtlsdr-dev

# Windows
# Download from https://osmocom.org/projects/rtl-sdr/wiki

2. RTL-SDR Tools:

# macOS
brew install rtl-sdr

# Ubuntu/Debian
sudo apt-get install rtl-sdr

# Includes: rtl_fm, rtl_adsb, rtl_test

3. SatDump for Meteor-M LRPT decoding (required for weather satellites):

# macOS
brew install satdump

# Fix SatDump resource paths (required on macOS - the cask doesn't set these up correctly)
# Step 1: Symlink all resources to /usr/local/share/satdump/
sudo mkdir -p /usr/local/share/satdump
cd /Applications/SatDump.app/Contents/Resources
sudo cp -R * /usr/local/share/satdump/

# Step 2: Symlink plugins directory to /usr/local/lib/satdump/
sudo mkdir -p /usr/local/lib/satdump
sudo ln -sf /Applications/SatDump.app/Contents/Resources/plugins /usr/local/lib/satdump/plugins

# Ubuntu/Debian
sudo add-apt-repository ppa:satdump/satdump
sudo apt-get update
sudo apt-get install satdump

# Enables Meteor-M2-3/M2-4 LRPT weather satellite decoding

4. rtl_433 for ISM band decoding (optional but recommended):

# macOS
brew install rtl_433

# Ubuntu/Debian
sudo apt-get install rtl-433

# Enables decoding of 433MHz/315MHz devices

5. POCSAG Decoder (optional):

# Clone and build multimon-ng
cd /tmp
git clone https://github.com/EliasOenal/multimon-ng.git
cd multimon-ng
mkdir build && cd build
cmake ..
make

# Binary will be at: /tmp/multimon-ng/build/multimon-ng

5. Python 3.10+

Install from Source

# Clone the repository
git clone https://github.com/yourusername/AetherLink-SDR-MCP
cd AetherLink-SDR-MCP

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Required Python Packages

The following are installed automatically:

  • pyrtlsdr - RTL-SDR hardware interface
  • numpy - Signal processing
  • scipy - Filtering and demodulation
  • mcp - Model Context Protocol server
  • Pillow - Image processing for NOAA satellite images
  • pyModeS - ADS-B decoding (optional)

🎯 Quick Start

1. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "sdr": {
      "command": "/Users/YOUR_USERNAME/Documents/GitHub/AetherLink-SDR-MCP/venv/bin/python",
      "args": ["-m", "sdr_mcp.server"],
      "env": {}
    }
  }
}

Important: Use absolute paths for the Python interpreter.

2. Restart Claude Desktop

Quit and restart Claude Desktop to load the MCP server.

3. Test the Connection

In Claude Desktop:

Connect to my RTL-SDR

You should see: "Successfully connected to RTL-SDR"

📡 Supported Hardware

Device RX Frequency TX Support Status Tested
RTL-SDR 24 MHz - 1766 MHz ❌ ✅ Stable ✅ Yes
HackRF One 1 MHz - 6 GHz ✅ ✅ Working ⚠️ Limited
Nooelec E4000 55 MHz - 2300 MHz ❌ ✅ Stable ✅ Yes

📊 Protocol Support

Protocol Description Status
ADS-B Aircraft tracking ✅ Ready
POCSAG Pager decoding ✅ Ready
AIS Ship tracking ✅ Ready
Meteor-M LRPT Weather satellites (M2-3, M2-4) ✅ Ready
NOAA APT Weather satellites (DEPRECATED) ⚠️ EOL Aug 2025
ISM Band 433MHz/315MHz devices ✅ Ready

Protocol Details

ADS-B (1090 MHz):

  • Uses rtl_adsb subprocess for demodulation
  • pyModeS for message decoding
  • Tracks aircraft position, speed, altitude, callsign
  • FULLY TESTED AND WORKING

POCSAG (152/454/929 MHz):

  • Uses multimon-ng for professional decoding
  • Supports 512/1200/2400 baud
  • Alphanumeric and numeric messages
  • Common frequencies: 152.240 MHz, 454 MHz, 929-931 MHz

AIS (161.975/162.025 MHz):

  • GMSK demodulation (simplified)
  • Decodes ship position, speed, type
  • Requires coastal location

Meteor-M LRPT (137 MHz):

  • Uses satdump subprocess for OQPSK demodulation
  • Digital LRPT transmission with error correction
  • Decodes visible and infrared channels
  • Active satellites: Meteor-M2-3 (137.9 MHz), Meteor-M2-4 (137.9 MHz primary, 137.1 MHz backup)
  • CURRENT WEATHER SATELLITE STANDARD (replaced NOAA APT)

NOAA APT (137 MHz) - DEPRECATED:

  • AM demodulation (analog)
  • All NOAA APT satellites decommissioned August 2025
  • Tool remains for historical/testing purposes
  • ⚠️ Use Meteor-M LRPT for current weather satellite imaging

ISM Band (433/315/868/915 MHz):

  • Uses rtl_433 subprocess for decoding
  • Multi-frequency hopping support
  • Decodes 200+ device types automatically
  • Weather stations, sensors, doorbells, tire pressure monitors, remote controls
  • Common frequencies: 433.92 MHz (EU/Asia), 315 MHz (NA), 868 MHz (EU), 915 MHz (NA)

🛠️ Available MCP Tools (27 Total)

Core SDR Control (5 tools)

  • sdr_connect - Connect to RTL-SDR or HackRF
  • sdr_disconnect - Disconnect from SDR
  • sdr_set_frequency - Set center frequency in Hz
  • sdr_set_gain - Set gain (dB or 'auto')
  • sdr_get_status - Get hardware status

Aviation (3 tools)

  • aviation_track_aircraft - Start ADS-B tracking on 1090 MHz
  • aviation_stop_tracking - Stop tracking
  • aviation_get_aircraft - Get list of tracked aircraft

Pager Decoding (3 tools)

  • pager_start_decoding - Start POCSAG decoder
  • pager_stop_decoding - Stop decoding
  • pager_get_messages - Get decoded messages

Marine (3 tools)

  • marine_track_vessels - Start AIS ship tracking
  • marine_stop_tracking - Stop tracking
  • marine_get_vessels - Get vessel list

Weather Satellites (2 tools)

  • satellite_decode_meteor - Decode Meteor-M2-3/M2-4 LRPT satellite pass (CURRENT)
  • satellite_decode_noaa - Decode NOAA APT satellite pass (DEPRECATED - satellites decommissioned)

ISM Band Devices (3 tools)

  • ism_start_scanning - Start scanning ISM bands (433/315/868/915 MHz) with multi-frequency hopping
  • ism_stop_scanning - Stop ISM band scanning
  • ism_get_devices - Get detected devices (weather stations, sensors, etc.)

Analysis (5 tools)

  • spectrum_analyze - Analyze RF spectrum (FFT, signal detection)
  • spectrum_scan - Scan frequency range
  • recording_start/recording_stop - Record raw IQ samples (saved to /tmp/sdr_recordings/)
  • audio_record_start/audio_record_stop - Record demodulated audio as WAV (FM/AM)

HackRF Transmit (2 tools)

  • hackrf_set_tx_gain - Set transmit gain
  • signal_generator - Generate and transmit signals

📖 Usage Examples

Track Aircraft

Track aircraft in my area

After 30-60 seconds:

Show me the aircraft

Decode Pagers

Set frequency to 152.240 MHz
Start paging decoder at 1200 baud

Wait a few minutes, then:

Get pager messages

Note: Check RadioReference.com for active pager frequencies in your area.

Analyze Spectrum

Set frequency to 100 MHz
Analyze the spectrum

Scan for Signals

Scan from 430 MHz to 440 MHz with 1 MHz steps

Record Audio from FM Radio

Set frequency to 103.7 MHz
Start audio recording with FM modulation and description "Local FM station"

Wait for desired duration (e.g., 30 seconds), then:

Stop audio recording

Files saved to: /tmp/sdr_recordings/audio_YYYYMMDD_HHMMSS_XXXMHz_FM.wav

Record Raw IQ Samples

Set frequency to 103.7 MHz
Start recording with description "Raw baseband data"

Wait for desired duration, then:

Stop recording

Files saved to: /tmp/sdr_recordings/recording_YYYYMMDD_HHMMSS_XXXMHz.iq

Use case: Advanced analysis, replay, or processing with GNU Radio/SDR#

Meteor-M Weather Satellite (when overhead)

Decode Meteor-M2-4 satellite for 600 seconds

Requirements:

  • SatDump installed (brew install satdump)
  • Satellite pass overhead (use tools like Gpredict, N2YO, or Heavens-Above to predict passes)
  • Ideally a V-dipole antenna tuned for 137 MHz

What you get:

  • Visible light channel images
  • Infrared channel images
  • Composite RGB images
  • Saved to /tmp/sdr_recordings/meteor_METEOR-M2-4_*/

Tips:

  • Meteor-M2-4 transmits on 137.9 MHz (primary) or 137.1 MHz (backup)
  • Best results with satellite elevation >30°
  • Full pass is typically 10-15 minutes
  • Use higher gain (40-49 dB) for weak signals

NOAA Satellite - DEPRECATED

Decode NOAA-19 satellite for 600 seconds

⚠️ Note: All NOAA APT satellites were decommissioned in August 2025. This tool remains for historical purposes only. Use satellite_decode_meteor for current weather satellite imaging.

Scan ISM Band Devices

Start ISM scanning on 433.92 MHz and 315 MHz with 30 second hop interval

Wait 1-2 minutes for devices to transmit, then:

Show me the ISM devices

Common devices detected:

  • Weather stations (temperature, humidity, wind, rain)
  • Wireless thermometers
  • Tire pressure monitoring systems (TPMS)
  • Door/window sensors
  • Doorbells and remote controls
  • Soil moisture sensors

Tips:

  • Weather stations typically transmit every 30-60 seconds
  • 433.92 MHz is common in Europe/Asia
  • 315 MHz is common in North America
  • Try different frequency combinations: [433.92, 315] or [868, 915]
  • Increase hop interval for more dwell time per frequency

🔧 Development

Project Structure

AetherLink-SDR-MCP/
├── sdr_mcp/
│   ├── server.py              # Main MCP server (26 tools)
│   ├── hardware/
│   │   ├── rtlsdr.py         # RTL-SDR interface
│   │   └── hackrf.py         # HackRF interface
│   ├── decoders/
│   │   ├── pocsag.py         # POCSAG pager decoder
│   │   ├── ais.py            # AIS ship decoder
│   │   ├── noaa_apt.py       # NOAA satellite decoder
│   │   └── rtl433.py         # ISM band device decoder
│   └── analysis/
│       └── spectrum.py        # Spectrum analysis, signal detection
├── tests/                     # All test scripts
└── README.md                  # This file

Architecture

Device Management:

  • RTL-SDR and subprocess decoders use exclusive device access
  • Python SDR control and subprocess tools (rtl_adsb, rtl_433) cannot run simultaneously
  • Subprocess-based decoders automatically disconnect Python SDR
  • Stopping decoder reconnects Python SDR control

Decoders:

  • ADS-B: rtl_adsb subprocess + pyModeS
  • ISM Band: rtl_433 subprocess with JSON output + multi-frequency hopping
  • POCSAG: rtl_fm + multimon-ng pipeline
  • AIS: Built-in GMSK demodulator (simplified)
  • NOAA: Built-in AM demodulator + sync detection

About

SDR MCP server

Resources

Readme
Activity

Stars

7 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1

Languages