MCP Servers¶
QSO Graph provides 22 MCP servers (150 tools), plus the qso-graph-auth credential foundation and the qsp-client relay, covering amateur radio logging, confirmations, propagation services, and local LLM integration. Start with Getting Started.
How it works¶
The servers are MCP servers: they run locally on your machine and expose ham radio services as tools that AI assistants can call. Your credentials stay in your OS keyring and never leave your machine.
You: "Do I have any new LoTW confirmations this week?"
│
▼
AI Assistant (Claude, ChatGPT, Cursor, etc.)
│
▼ calls lotw_confirmations(persona="ki7mt", since="2026-03-01")
│
lotw-mcp (local process)
│
▼ HTTPS request to lotw.arrl.org (credentials from OS keyring)
│
LoTW API
│
▼ ADIF response
│
You: "You have 3 new confirmations: JA1ABC on 20m FT8, ..."
Fleet Summary¶
Foundation¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| qso-graph-auth | — | OS keyring credentials | None (local) |
| adif-mcp | 8 | ADIF 3.1.7 spec | None (local) |
Logbook Services¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| eqsl-mcp | 6 | eQSL.cc | Persona (session) |
| qrz-mcp | 6 | QRZ.com | Persona (XML) + API key (Logbook) |
| lotw-mcp | 6 | LoTW (ARRL) | Persona (HTTPS) |
| hamqth-mcp | 8 | HamQTH.com | Persona (XML session) |
Public Services¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| pota-mcp | 11 | Parks on the Air | None (public) |
| sota-mcp | 5 | Summits on the Air | None (public) |
| iota-mcp | 7 | Islands on the Air | None (public) |
| solar-mcp | 7 | NOAA SWPC | None (public) |
| wspr-mcp | 9 | wspr.live (ClickHouse) | None (public) |
| omiss-mcp | 14 | OMISS (omiss.net) | None (public) |
Propagation Analytics¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| ionis-mcp | 12 | IONIS-AI signature datasets | None (local) |
Reference Data¶
The lists ADIF's fields point to but ADIF doesn't define, each as its owner publishes it and credited to that owner. The facts ship with the package; the owner's document doesn't.
| Package | Tools | Owner's list | Auth Pattern |
|---|---|---|---|
| cq-zones-mcp | 6 | CQ zones: CQ's WAZ Zone Definitions | None (local) |
| itu-zones-mcp | 6 | ITU zones: the IARU's HF Managers Handbook, ch. 9.8 | None (local) |
| darc-dok-mcp | 6 | DARC's DOKs and special DOKs | None (local) |
Radio Logging¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| n1mm-mcp | 12 | N1MM Logger+ (UDP broadcast) | None (local) |
| netlogger-mcp | 6 | NetLogger | Callsign (public API) |
Infrastructure¶
| Package | Purpose | Auth Pattern |
|---|---|---|
| qsp-client | QSP — relay MCP tools to any local LLM endpoint | None (local) |
Authentication Patterns¶
Persona Auth (OS Keyring)¶
eQSL, QRZ, LoTW, and HamQTH use qso-graph-auth personas — named identities with credentials stored in your OS keyring:
Every tool call includes a persona parameter so the server knows which credentials to use. See Getting Started for setup.
Public (No Auth)¶
POTA, SOTA, IOTA, Solar, WSPR and OMISS servers access public data — no credentials needed. Just install and go.
Architecture¶
All servers share a common architecture:
AI Assistant
│
▼ MCP protocol (stdio)
│
MCP Server (local process)
│
├── Rate Limiter (prevents account bans)
├── Input Validator (regex on all user strings)
├── Response Cache (in-memory TTL)
│
▼ HTTPS only
│
External API (eQSL, QRZ, LoTW, etc.)
Common Properties¶
- Transport: stdio (default) or
--transport streamable-httpfor MCP Inspector - Framework: FastMCP 3.x
- Python: 3.10+
- License: GPL-3.0-or-later
- Mock mode: Every server supports
<NAME>_MCP_MOCK=1for testing without credentials
Rate Limiting¶
Each server implements rate limiting appropriate for its service:
| Server | Min Delay | Max Rate | Ban Freeze |
|---|---|---|---|
| eqsl-mcp | 500ms | — | — |
| qrz-mcp | 500ms | 35/min | 3600s (IP ban) |
| lotw-mcp | 500ms | — | — |
| hamqth-mcp | 500ms | — | — |
| pota-mcp | 100ms | — | — |
| sota-mcp | 200ms | — | — |
| iota-mcp | 200ms | — | — |
| solar-mcp | 200ms | — | — |
| wspr-mcp | 3000ms | 20/min | Circuit breaker (60-300s) |
| omiss-mcp | 2000ms | 30/min, shared by every copy | 429/503 back-off (60-3600s) |