AetherLink: Software Defined Radio Model Context Protocol Server

You can control compatible software defined radios and decode radio protocols through a Model Context Protocol interface, enabling seamless integration with MCP clients to run, monitor, and analyze RF signals from your own hardware setup.

How to use

You will run a local MCP server that exposes radio control and decoding capabilities to MCP clients. Start the server, connect with your MCP client, and issue natural language commands or scripted requests to connect to SDR hardware, tune frequencies, run protocol decoders, and perform real-time spectrum analysis.

How to install

Prerequisites include hardware driver support and Python 3.10 or newer. You will install a local Python environment, install the server package, and then run the MCP server as a local process.

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

# Prerequisites on macOS
brew install librtlsdr

# Prerequisites on Windows
# Install from https://osmocom.org/projects/rtl-sdr/wiki

# Ensure Python 3.10+ is available
python3 --version

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

# Install the MCP server package (editable) with basic dependencies
pip install -e .

# Optional: install with all protocol decoders
pip install -e ".[decoders]"

# Optional: install with HackRF support
pip install -e ".[hackrf]"

Additional sections

Configuration patterns, security considerations, and practical usage notes help you get the most from the MCP server. The following sections provide concrete, actionable details you can apply immediately.

Configure your MCP client to connect to the local server so you can issue commands like starting the SDR, tracking signals, and analyzing spectra. The server is designed to be invoked as a local stdio process from your MCP client setup.

Security considerations include running the server in a trusted environment, restricting access to the MCP client interface, and keeping the SDR hardware drivers up to date to prevent unauthorized access to your RF hardware.

Troubleshooting basics: ensure the SDR hardware is recognized by the system, verify Python virtual environment activation, and check that any required protocol decoders are installed if you encounter decoding or analysis issues.

Notes: when you install with decoders or HackRF support, you enable broader capabilities for protocol decoding and hardware control. If you need to start debugging or monitoring, you can run the server in a development environment and attach your MCP client for interactive control.

Configuration example for MCP client connection

{
  "mcpServers": {
    "aetherlink": {
      "command": "python",
      "args": ["-m", "sdr_mcp.server"],
      "env": {}
    }
  }
}

Notes on hardware and protocol support

This server supports RTL-SDR and HackRF hardware for direct control, with real-time spectrum analysis and various protocol decoders. You can expand capabilities by installing additional decoders during the Python package installation process.

Available tools

sdr_connect

Connect to SDR hardware to establish a control session.

sdr_disconnect

Terminate the current control session with the SDR hardware.

sdr_set_frequency

Set the center frequency for the connected SDR device.

sdr_set_gain

Adjust the RF gain for the input path.

sdr_get_status

Query the current status of the SDR hardware.

aviation_track_aircraft

Start ADS-B tracking to monitor aircraft in range.

spectrum_analyze

Perform real-time spectrum analysis of the received RF signal.

spectrum_scan

Scan a specified frequency range to identify active signals.

recording_start/stop

Begin or end recording of IQ samples for later analysis.