Qrz Mcp

io.github.qso-graphPublished by GitHub account qso-graphv0.6.2Updated Nov 3, 2026

QRZ.com MCP server. Callsign lookup, DXCC resolution, logbook queries via QRZ XML API.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Local MCP server for QRZ.com that lets an assistant look up amateur radio callsigns, resolve DXCC entities, and query or download your QRZ logbook.

What you can do
  • Look up callsigns on QRZ.com for name, grid, DXCC, license class, QSL info and image
  • Resolve a DXCC entity from a callsign or numeric entity code
  • Read logbook statistics such as QSO count, DXCC total and date range
  • Query QSOs from your logbook with filters and pagination, oldest or newest first
  • Download the full logbook as raw ADIF text for import into a logger
  • Report the service version and upstream QRZ API version for fleet comparison
When to use it
Useful for radio amateurs and QSO-logging workflows where an assistant should answer callsign questions, identify DXCC entities, or summarize and export QRZ logbook contacts without manual lookups.
Requirements
Runs locally via uvx (Python). Credentials are managed through qso-graph-auth personas: a QRZ username and password for the XML API, and a QRZ username and API key for the logbook API; the persona name is passed on each tool call. A paid QRZ XML subscription is needed for full lookup fields, DXCC and logbook access. Network access to QRZ.com.
Before you install
The server handles QRZ account credentials (password and API key) stored through qso-graph-auth; the README advises entering them at a prompt rather than as CLI arguments. Lookups and logbook queries send callsigns and account data to QRZ.com. The logbook download returns your full contact log. QRZ enforces undocumented rate limits that can cause 24-hour IP bans, which the server throttles to avoid.

Installation

In SourceWeft

  1. Open Qrz Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

qrz-mcp

[PyPI] [MCP Registry]

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

bash
uvx qrz-mcp            # run it; nothing to install

Tools

ToolAPIAuthDescription
qrz_lookupXMLSession keyCallsign lookup (name, grid, DXCC, license class, QSL info, image)
qrz_dxccXMLSession keyDXCC entity resolution from callsign or entity code
qrz_logbook_statusLogbookAPI keyLogbook stats (QSO count, DXCC total, date range)
qrz_logbook_fetchLogbookAPI keyQuery QSOs with filters and transparent pagination
qrz_downloadLogbookAPI keyDownload full logbook as ADIF
get_version_info—NoneService 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:

ProviderToolsCredentials
qrzqrz_lookup, qrz_dxccusername + password
qrz_logbookqrz_logbook_status, qrz_logbook_fetch, qrz_downloadusername + API key
bash
# Install qso-graph-auth if you haven'tuv tool install qso-graph-auth
# Create a persona (--start is required)qso-graph-auth persona add --name ki7mt --callsign KI7MT --start 2018-01-01
# XML API (qrz_lookup, qrz_dxcc)qso-graph-auth provider enable ki7mt qrzqso-graph-auth creds set ki7mt qrz              # asks for your username, then your password (hidden)
# Logbook API (qrz_logbook_status, qrz_logbook_fetch, qrz_download)qso-graph-auth provider enable ki7mt qrz_logbookqso-graph-auth creds set ki7mt qrz_logbook      # asks for your username, then your API key
# Verifyqso-graph-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):

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

Add to .claude/settings.json:

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:

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

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

json
{  "mcpServers": {    "qrz": {      "command": "uvx",      "args": ["qrz-mcp"]    }  }}
VS Code / GitHub Copilot

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

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

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

json
{  "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:

bash
QRZ_MCP_MOCK=1 qrz-mcp

MCP Inspector

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

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

Development

bash
git clone https://github.com/qso-graph/qrz-mcp.gitcd qrz-mcpuv sync --group devuv run pytest

QRZ Subscription Tiers

FeatureFreeXML Data ($35.95/yr)
Callsign lookups/day100Unlimited
Fields returnedName + address onlyAll (grid, lat/lon, DXCC, class, QSL, image)
Logbook APINoYes
DXCC lookupNoYes

License

GPL-3.0-or-later

Source: README.md at commit c6c5a99

Tools

6

get_version_info

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.

Takes no parameters.

qrz_lookup

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.

Parameterspersonarequiredcallsignrequired

qrz_dxcc

Qrz Dxcc

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

Parametersqueryrequiredpersonarequired

qrz_logbook_status

Qrz Logbook Status

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

Parameterspersonarequired

qrz_download

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.

Parametersbandmodepersonarequiredend_datestart_date

qrz_logbook_fetch

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

Parametersbanddxccmodelimitpersonarequiredcallsignend_datestart_datenewest_firstconfirmed_only

Version history

12
  1. v0.6.2LatestOct 29, 2026
  2. v0.5.0Oct 26, 2026
  3. v0.4.4Oct 26, 2026
  4. v0.4.2Oct 26, 2026
  5. v0.4.1Oct 14, 2026
  6. v0.4.0Oct 12, 2026
  7. v0.3.9Oct 11, 2026
  8. v0.3.8Oct 7, 2026
  9. v0.3.7Oct 6, 2026
  10. v0.3.6Oct 4, 2026
  11. v0.3.5Sep 29, 2026
  12. v0.2.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts