io.github.qso-graph/lotw-mcp

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 install

Tools

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-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-auth provider enable ki7mt lotw
qso-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-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
uv sync --group dev
uv run pytest

License

GPL-3.0-or-later