Server Overview¶
QSO-Graph provides 14 packages (12 MCP servers + auth foundation + LLM relay) covering amateur radio logging, confirmations, propagation services, and local LLM integration.
Fleet Summary¶
Foundation¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| qso-graph-auth | — | OS keyring credentials | None (local) |
| adif-mcp | 8 | ADIF 3.1.6 spec | None (local) |
Logbook Services¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| eqsl-mcp | 5 | eQSL.cc | Persona (session) |
| qrz-mcp | 5 | QRZ.com | Persona (XML) + API key (Logbook) |
| lotw-mcp | 5 | LoTW (ARRL) | Persona (HTTPS) |
| hamqth-mcp | 7 | HamQTH.com | Persona (XML session) |
Public Services¶
| Package | Tools | Service | Auth Pattern |
|---|---|---|---|
| pota-mcp | 7 | Parks on the Air | None (public) |
| sota-mcp | 4 | Summits on the Air | None (public) |
| iota-mcp | 6 | Islands on the Air | None (public) |
| solar-mcp | 6 | NOAA SWPC | None (public) |
| wspr-mcp | 8 | wspr.live (ClickHouse) | None (public) |
Infrastructure¶
| Package | Purpose | Auth Pattern |
|---|---|---|
| qsp-mcp | QSP — relay MCP tools to any local LLM endpoint | None (local) |
| llm-stack | Docker Compose — Open WebUI + llama.cpp + MCP tools in a browser | 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, and WSPR servers access public APIs — 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) |