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¶

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:

# 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

Tool Reference¶

Generated from the released server's own tool definitions.

get_version_info¶

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.

No parameters.

lotw_confirmations¶

Query confirmed QSL records from LoTW.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`since`	string	No	`null`	QSLs received since this date (YYYY-MM-DD). Default: last 30 days.
`band`	string	No	`null`	Filter by ADIF band (e.g., '20M').
`mode`	string	No	`null`	Filter by ADIF mode (e.g., 'FT8').
`callsign`	string	No	`null`	Filter by worked station callsign.
`dxcc`	integer	No	`null`	Filter by DXCC entity code.
`detail`	boolean	No	`true`	Include QSL station location data (default true).

lotw_download¶

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

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`qsl_only`	boolean	No	`false`	Only return confirmed QSLs (default: all uploaded QSOs).
`since`	string	No	`null`	Only records since this date (YYYY-MM-DD). Omit for full history.
`band`	string	No	`null`	Filter by band (e.g., '20M').
`mode`	string	No	`null`	Filter by mode (e.g., 'FT8').

lotw_dxcc_credits¶

Query DXCC award credits from LoTW confirmations.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`entity`	integer	No	`null`	Optional DXCC entity code to filter by.

lotw_qsos¶

Query all uploaded QSOs from LoTW (confirmed and unconfirmed).

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`since`	string	No	`null`	QSOs uploaded since this date (YYYY-MM-DD). Default: last 30 days.
`band`	string	No	`null`	Filter by band (e.g., '20M').
`mode`	string	No	`null`	Filter by mode (e.g., 'FT8').
`start_date`	string	No	`null`	QSO date range start (YYYY-MM-DD).
`end_date`	string	No	`null`	QSO date range end (YYYY-MM-DD).

lotw_user_activity¶

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

Parameter	Type	Required	Default	Description
`callsign`	string	Yes		Callsign to check.