AetherLink SDR MCP
Enables control of Software Defined Radios and decoding of radio protocols through an AI-friendly Model Context Protocol interface, supporting RTL-SDR and HackRF hardware for signal analysis and protocol decoding.
README Documentation
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 interfacenumpy- Signal processingscipy- Filtering and demodulationmcp- Model Context Protocol serverPillow- Image processing for NOAA satellite imagespyModeS- 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_adsbsubprocess for demodulation - pyModeS for message decoding
- Tracks aircraft position, speed, altitude, callsign
- FULLY TESTED AND WORKING
POCSAG (152/454/929 MHz):
- Uses
multimon-ngfor 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
satdumpsubprocess 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_433subprocess 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 HackRFsdr_disconnect- Disconnect from SDRsdr_set_frequency- Set center frequency in Hzsdr_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 MHzaviation_stop_tracking- Stop trackingaviation_get_aircraft- Get list of tracked aircraft
Pager Decoding (3 tools)
pager_start_decoding- Start POCSAG decoderpager_stop_decoding- Stop decodingpager_get_messages- Get decoded messages
Marine (3 tools)
marine_track_vessels- Start AIS ship trackingmarine_stop_tracking- Stop trackingmarine_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 hoppingism_stop_scanning- Stop ISM band scanningism_get_devices- Get detected devices (weather stations, sensors, etc.)
Analysis (5 tools)
spectrum_analyze- Analyze RF spectrum (FFT, signal detection)spectrum_scan- Scan frequency rangerecording_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 gainsignal_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_adsbsubprocess + pyModeS - ISM Band:
rtl_433subprocess with JSON output + multi-frequency hopping - POCSAG:
rtl_fm+multimon-ngpipeline - AIS: Built-in GMSK demodulator (simplified)
- NOAA: Built-in AM demodulator + sync detection