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

pip install lotw-mcp

Tools

| Tool | Auth | Description |
|------|------|-------------|
| lotw_confirmations | Yes | Query confirmed QSLs with band/mode/call/date filters |
| lotw_qsos | Yes | Query all uploaded QSOs (confirmed and unconfirmed) |
| lotw_dxcc_credits | Yes | DXCC award credits from LoTW confirmations |
| lotw_download | Yes | Download QSOs as ADIF file |
| lotw_user_activity | No | Check if a callsign uses LoTW and when they last uploaded |
| get_version_info | 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:

pip install qso-graph-auth
qso-auth persona create ki7mt --callsign KI7MT

qso-auth persona provider ki7mt lotw --username KI7MT

qso-auth persona secret ki7mt lotw

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": "lotw-mcp"
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "lotw": {
      "command": "lotw-mcp"
    }
  }
}

ChatGPT Desktop

{
  "mcpServers": {
    "lotw": {
      "command": "lotw-mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "lotw": {
      "command": "lotw-mcp"
    }
  }
}

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "lotw": {
      "command": "lotw-mcp"
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "lotw": {
      "command": "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-mcp

Performance Notes

LoTW can be slow (30-60s for large queries). lotw-mcp uses 120s timeouts. Use date filters (since, start_date) to limit result sets.

MCP Inspector

lotw-mcp --transport streamable-http --port 8004

Development

git clone https://github.com/qso-graph/lotw-mcp.git
cd lotw-mcp
pip install -e .

License

GPL-3.0-or-later