Lotw MCP server

<!-- mcp-name: 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

pip install lotw-mcp

Tools

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 claudedesktopconfig.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

lotwuseractivity 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