lotw-mcp
Read-only MCP server for querying ARRL Logbook of The World (LoTW) data.
Query confirmed QSLs with band, mode, DXCC entity, callsign, and date filters.
Query all uploaded QSOs, confirmed and unconfirmed, with band, mode, and date-range filters.
Retrieve DXCC award credits from LoTW confirmations.
Download LoTW logs as raw ADIF, optionally QSL-only and filtered by band, mode, or date.
Check whether a callsign uses LoTW and when they last uploaded using public cached activity data without authentication.
Get service version and upstream LoTW schema version for fleet alignment/drift detection.
Enables querying ARRL Logbook of The World (LoTW) confirmations, uploaded QSOs, DXCC credits, and user activity through GitHub Copilot.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lotw-mcp How many LoTW confirmations did I get this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lotw-mcp
MCP server for ARRL Logbook of The World (LoTW)—query confirmations, uploaded QSOs, DXCC credits, and user activity through any MCP-compatible AI assistant.
Part of the qso-graph project. Read-only—uploads require TQSL digital signatures and are out of scope.
Install
uvx lotw-mcp # run it; nothing to installRelated MCP server: hamqth-mcp
Tools
Tool | Auth | Description |
| Yes | Query confirmed QSLs with band/mode/call/date filters |
| Yes | Query all uploaded QSOs (confirmed and unconfirmed) |
| Yes | DXCC award credits from LoTW confirmations |
| Yes | Download QSOs as ADIF file |
| No | Check if a callsign uses LoTW and when they last uploaded |
| No | Service version + upstream LoTW schema version (fleet identity attestation) |
Quick Start
1. Set up credentials
lotw-mcp uses qso-graph-auth personas for credential management:
# Install qso-graph-auth if you haven't
uv tool install qso-graph-auth
# A persona (your callsign and the dates it covers), then LoTW for it
qso-graph-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-graph-auth provider enable ki7mt lotw
qso-graph-auth creds set ki7mt lotw # asks for your username, then your password (hidden)All three steps are needed: without provider enable, the server reports that the persona has no lotw ref.
Note: The LoTW login is usually your callsign but not always. Pre-Sept 2019 accounts may require lowercase passwords. Avoid special characters in passwords.
2. Configure your MCP client
Claude Desktop
Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):
{
"mcpServers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}Claude Code
Add to .claude/settings.json:
{
"mcpServers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}ChatGPT Desktop
{
"mcpServers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}Cursor
Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}VS Code / GitHub Copilot
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}Gemini CLI
Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):
{
"mcpServers": {
"lotw": {
"command": "uvx",
"args": ["lotw-mcp"]
}
}
}3. Ask questions
"How many LoTW confirmations did I get this month?"
"Show me all unconfirmed 20m FT8 QSOs uploaded to LoTW in the last 90 days"
"What DXCC credits do I have on 40m CW?"
"Does JA1ABC use LoTW? When did they last upload?"
Public Tool
lotw_user_activity works without any credentials. It uses the public LoTW user activity CSV, cached locally for 7 days.
Testing Without Credentials
Set the mock environment variable:
LOTW_MCP_MOCK=1 lotw-mcpPerformance Notes
LoTW can be slow (30-60 s for large queries). lotw-mcp uses 120 s timeouts. Use date filters (since, start_date) to limit result sets.
MCP Inspector
lotw-mcp --transport streamable-http --port 8004Development
git clone https://github.com/qso-graph/lotw-mcp.git
cd lotw-mcp
uv sync --group dev
uv run pytestLicense
GPL-3.0-or-later
Available Tools
6 toolsget_version_infoGet Version InfoARead-onlyIdempotent
Get lotw-mcp service version and upstream LoTW schema version.
Returns the running PyPI version of lotw-mcp and the ARRL LoTW ADIF/CSV export schema in use. Use this to confirm fleet alignment across MCP deployments — agents can compare service_version and spec_version across servers to detect drift without going outside the MCP protocol.
Inputs: no named parameters. Returns: object
lotw_confirmationsLotw ConfirmationsBRead-onlyIdempotent
Query confirmed QSL records from LoTW.
Inputs: persona (required), band, dxcc, mode, +3 more. Returns: object
lotw_downloadLotw DownloadARead-onlyIdempotent
Download your complete LoTW log as raw ADIF text.
Returns the .adi file content — save to disk for import into your logger. Set qsl_only=True for confirmed QSLs only. Omit 'since' for full history. Warning: large logs may take 30-60 seconds (LoTW is slow).
Inputs: persona (required), band, mode, since, +1 more. Returns: object
lotw_dxcc_creditsLotw Dxcc CreditsBRead-onlyIdempotent
Query DXCC award credits from LoTW confirmations.
Inputs: persona (required), entity. Returns: object
lotw_qsosLotw QsosBRead-onlyIdempotent
Query all uploaded QSOs from LoTW (confirmed and unconfirmed).
Inputs: persona (required), band, mode, since, +2 more. Returns: object
lotw_user_activityLotw User ActivityARead-onlyIdempotent
Check if a callsign uses LoTW and when they last uploaded.
Public endpoint — no authentication required. Uses a locally cached copy of the LoTW user activity CSV (refreshed weekly).
Inputs: callsign (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools mostly target distinct LoTW resources: confirmations, DXCC credits, all QSOs, raw log download, user activity, and version info. There is mild overlap between lotw_confirmations and lotw_qsos (confirmed subset vs all QSOs), but descriptions make the boundary clear.
Most tools use a consistent lotw_ domain prefix followed by a noun/action, e.g. lotw_confirmations, lotw_dxcc_credits, lotw_qsos. get_version_info deviates with a generic verb_noun pattern, but overall the set remains readable and predictable.
Six tools is well-scoped for a LoTW query/download server. Each tool covers a distinct capability without obvious filler or missing core operations.
The surface covers the main read-only LoTW workflows: QSO lookup, confirmations, DXCC credits, raw ADIF download, and callsign activity. Minor gaps exist for richer award queries (e.g. WAS/WAC) or detailed per-QSO inspection, but agents can work around them with the current tools.
Maintenance
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityAmaintenanceAn MCP server for eQSL.cc that allows users to download incoming electronic QSL cards, verify specific contacts, and check Authenticity Guaranteed status. It enables natural language interaction with amateur radio logs and confirmation records through any MCP-compatible AI assistant.6145 PyPIGPL 3.0
- AlicenseAqualityAmaintenanceMCP server for HamQTH.com — callsign lookup, DX cluster spots, Reverse Beacon Network, DXCC resolution, and more through any MCP-compatible AI assistant.8126 PyPIGPL 3.0
- AlicenseAqualityAmaintenanceMCP server for QRZ.com — callsign lookups, DXCC entity resolution, and logbook queries through any MCP-compatible AI assistant.6269 PyPI4GPL 3.0
- AlicenseAqualityAmaintenanceEnables IOTA group lookup, island search, DXCC mapping, nearby groups, and programme statistics through any MCP-compatible AI assistant.7114 PyPIGPL 3.0