qrz-mcp¶

MCP server for QRZ.com — callsign lookups, DXCC entity resolution, and logbook queries through any MCP-compatible AI assistant.

Part of the qso-graph project. Uses qso-graph-auth for credential management.

Install¶

uvx qrz-mcp            # run it; nothing to install

Tools¶

Tool	API	Auth	Description
`qrz_lookup`	XML	Session key	Callsign lookup (name, grid, DXCC, license class, QSL info, image)
`qrz_dxcc`	XML	Session key	DXCC entity resolution from callsign or entity code
`qrz_logbook_status`	Logbook	API key	Logbook stats (QSO count, DXCC total, date range)
`qrz_logbook_fetch`	Logbook	API key	Query QSOs with filters and transparent pagination
`qrz_download`	Logbook	API key	Download full logbook as ADIF
`get_version_info`	—	None	Service version + upstream QRZ API version (fleet identity attestation)

Quick Start¶

1. Set up credentials¶

qrz-mcp uses qso-graph-auth personas for credential management. QRZ has two separate auth mechanisms, exposed as two providers — set up whichever you need:

Provider	Tools	Credentials
`qrz`	`qrz_lookup`, `qrz_dxcc`	username + password
`qrz_logbook`	`qrz_logbook_status`, `qrz_logbook_fetch`, `qrz_download`	username + API key

# Install qso-graph-auth if you haven't
uv tool install qso-graph-auth

# Create a persona (--start is required)
qso-auth persona add --name ki7mt --callsign KI7MT --start 2018-01-01

# XML API (qrz_lookup, qrz_dxcc)
qso-auth provider enable ki7mt qrz
qso-auth creds set ki7mt qrz              # asks for your username, then your password (hidden)

# Logbook API (qrz_logbook_status, qrz_logbook_fetch, qrz_download)
qso-auth provider enable ki7mt qrz_logbook
qso-auth creds set ki7mt qrz_logbook      # asks for your username, then your API key

# Verify
qso-auth creds doctor

Pass the persona name (ki7mt above) as the persona argument on every tool call.

Omit --password / --api-key to be prompted instead — passing secrets as CLI arguments leaves them in your shell history.

XML API (callsign lookup, DXCC) requires a QRZ XML Subscription ($35.95/yr). Free tier returns name and address only.

Logbook API requires an API key from QRZ Settings > API.

2. Configure your MCP client¶

qrz-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.

Claude Desktop¶

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

Claude Code¶

Add to .claude/settings.json:

{
  "mcpServers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

ChatGPT Desktop¶

ChatGPT supports MCP via the OpenAI Agents SDK. Add under Settings > Apps & Connectors, or configure in your agent definition:

{
  "mcpServers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

Cursor¶

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

{
  "mcpServers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

VS Code / GitHub Copilot¶

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

{
  "servers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

Gemini CLI¶

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

{
  "mcpServers": {
    "qrz": {
      "command": "uvx",
      "args": ["qrz-mcp"]
    }
  }
}

3. Ask questions¶

"Look up W1AW on QRZ — what's their grid and license class?"

"What DXCC entity is VP8PJ?"

"How many QSOs do I have in my QRZ logbook?"

"Show me all 20m FT8 QSOs from my QRZ logbook this year"

Rate Limiting¶

QRZ enforces undocumented rate limits that can trigger 24-hour IP bans. qrz-mcp protects you:

500ms minimum delay between all API calls
Token bucket: 35 requests/minute
60s freeze on authentication failures
3600s freeze on connection refused (IP ban detection)
In-memory response cache (5 min for callsigns, 1 hour for DXCC)

Testing Without Credentials¶

Set the mock environment variable to test all 6 tools without QRZ credentials:

QRZ_MCP_MOCK=1 qrz-mcp

MCP Inspector¶

qrz-mcp --transport streamable-http --port 8002

Then open the MCP Inspector at http://localhost:8002.

Development¶

git clone https://github.com/qso-graph/qrz-mcp.git
cd qrz-mcp
uv sync --group dev
uv run pytest

QRZ Subscription Tiers¶

Feature	Free	XML Data ($35.95/yr)
Callsign lookups/day	100	Unlimited
Fields returned	Name + address only	All (grid, lat/lon, DXCC, class, QSL, image)
Logbook API	No	Yes
DXCC lookup	No	Yes

License¶

GPL-3.0-or-later

Tool Reference¶

Generated from the released server's own tool definitions.

get_version_info¶

Get qrz-mcp service version and upstream QRZ API version.

Returns the running PyPI version of qrz-mcp and the QRZ.com XML + Logbook API contract 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.

qrz_download¶

Download your complete QRZ logbook as raw ADIF text.

Returns the .adi file content — save to disk for import into your logger. Transparently paginates to collect all records. Rate-limited to avoid API bans.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`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`	Date range start (YYYY-MM-DD).
`end_date`	string	No	`null`	Date range end (YYYY-MM-DD).

qrz_dxcc¶

Resolve a DXCC entity from a callsign or numeric entity code.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`query`	string	Yes		Callsign (e.g., VP8PJ) or DXCC code (e.g., 291).

qrz_logbook_fetch¶

Query QSOs from a QRZ logbook with optional filters.

Transparently paginates to collect up to limit records. QRZ returns records oldest first, so by default limit keeps the OLDEST matches. Set newest_first for the most recent QSOs instead (for example, "my last 10 contacts" is limit=10 with newest_first=true).

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`band`	string	No	`null`	Filter by band (e.g., '20m').
`mode`	string	No	`null`	Filter by mode (e.g., 'FT8').
`callsign`	string	No	`null`	Filter by contacted station.
`dxcc`	integer	No	`null`	Filter by DXCC entity code.
`start_date`	string	No	`null`	Date range start (YYYY-MM-DD).
`end_date`	string	No	`null`	Date range end (YYYY-MM-DD).
`confirmed_only`	boolean	No	`false`	Only return confirmed QSOs.
`limit`	integer	No	`250`	Maximum records to return (default 250).
`newest_first`	boolean	No	`false`	Return the newest `limit` matches, newest first.

qrz_logbook_status¶

Get QRZ logbook statistics (QSO count, DXCC total, date range).

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.

qrz_lookup¶

Look up a callsign on QRZ.com (name, grid, DXCC, license class, QSL info, image).

Requires a QRZ XML Subscription ($35.95/yr) for full fields.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`callsign`	string	Yes		Callsign to look up (e.g., W1AW).