aprs-mcp

Model Context Protocol (MCP) server exposing the APRS-IS network as tools for any LLM agent (opencode, Claude Desktop, Cursor, Windsurf, generic MCP clients). Built on aprslib and fastmcp.

Tools

aprs_listen filter syntax

Related MCP server: A2A Client MCP Server

Requirements

Requires Python 3.11+ and uv.

Installation

git clone https://github.com/gflerm/aprs-mcp.git
cd aprs-mcp
uv sync

cp credentials.example credentials

On Windows PowerShell, the included installer creates the virtual environment and credentials template:

.\install.ps1

MCP client configuration

Codex

Register the local STDIO server globally:

codex mcp add aprs -- ".venv\Scripts\aprs-mcp.exe"

On macOS or Linux, use .venv/bin/aprs-mcp instead. Restart Codex after registration, then run aprs_cmd_list to verify the connection.

Other clients

opencode — add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "aprs": {
      "type": "local",
      "command": [".venv/bin/aprs-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop — add to claude_desktop_config.json under mcpServers. Any other MCP client — point it at the mcp stdio transport with command .venv/bin/aprs-mcp (Windows: .venv\Scripts\aprs-mcp.exe).

Restart the agent after registering the server.

Credentials

The server reads network settings and station identity from a plain key=value file named credentials in the project. Copy credentials.example to credentials and fill in your own values.

The server looks for credentials in this order:

1. Next to the installed module (site-packages)

2. The project root (the checkout / install directory)

3. The current working directory

Existing environment variables always win; the file never overrides them.

Populate the credentials file as follows:

Getting your passcode. The passcode is a one-way hash of your base callsign — generate it once with the APRSPASS calculator shipped inside aprslib:

python -c "from aprslib import passcode; print(passcode('ZL1XXXX'))"

Then write the result into credentials:

APRS_CALLSIGN=ZL1XXXX
APRS_PASSCODE=12345
APRS_HOST=euro.aprs2.net
APRS_PORT=14580

Optionally add your aprs.fi key (free, low-volume) so aprs_position answers without waiting on the live stream.

credentials is your real file. credentials.example is the committed template. Never commit credentials.

Development

Install the project in its managed virtual environment:

uv sync
uv run python -m aprs_mcp.server

The MCP transport uses standard input/output. Client logs and diagnostics must go to standard error so they do not corrupt the protocol stream.

License

Released under the MIT License.