Qrz Mcp

qrz-mcp

适用于 QRZ.com 的 MCP 服务——通过任何兼容 MCP 的 AI 助手查询呼号、解析 DXCC 实体并查询日志。

本项目是 qso-graph 的一部分。使用 qso-graph-auth 管理凭据。

安装

uvx qrz-mcp            # run it; nothing to install

工具

工具	API	身份验证	描述
qrz_lookup	XML	会话密钥	呼号查询（姓名、网格、DXCC、执照等级、QSL 信息、图像）
qrz_dxcc	XML	会话密钥	根据呼号或实体代码解析 DXCC 实体
qrz_logbook_status	Logbook	API 密钥	日志统计（QSO 数量、DXCC 总数、日期范围）
qrz_logbook_fetch	Logbook	API 密钥	使用筛选条件查询 QSO，并自动分页
qrz_download	Logbook	API 密钥	将完整日志下载为 ADIF
get_version_info	—	无	服务版本 + 上游 QRZ API 版本（服务集群身份验证）

快速开始

1. 设置凭据

qrz-mcp 使用 qso-graph-auth persona 管理凭据。QRZ 有两种独立的身份验证机制，分别通过两个 provider 提供——按需设置：

Provider	工具	凭据
qrz	qrz_lookup、qrz_dxcc	用户名 + 密码
qrz_logbook	qrz_logbook_status、qrz_logbook_fetch、qrz_download	用户名 + API 密钥

# 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

在每次工具调用时，将 persona 名称（上例中的 ki7mt）作为 persona 参数传入。

省略 --password / --api-key 即可改为通过提示输入——将密钥作为 CLI 参数传入会把它们留在 shell 历史记录中。

XML API（呼号查询、DXCC）需要 QRZ XML Subscription（每年 $35.95）。免费层仅返回姓名和地址。

Logbook API 需要从 QRZ Settings > API 获取 API 密钥。

2. 配置 MCP 客户端

qrz-mcp 兼容任何 MCP 客户端。添加服务配置并重启后，工具会自动显示。

Claude Desktop

添加到 claude_desktop_config.json（macOS 上位于 ~/Library/Application Support/Claude/，Windows 上位于 %APPDATA%\Claude\）：

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

Claude Code

添加到 .claude/settings.json：

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

ChatGPT Desktop

ChatGPT 通过 OpenAI Agents SDK 支持 MCP。可在 Settings > Apps & Connectors 中添加，或在 Agent 定义中配置：

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

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

VS Code / GitHub Copilot

添加到工作区中的 .vscode/mcp.json：

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

Gemini CLI

添加到 ~/.gemini/settings.json（全局）或 .gemini/settings.json（项目级）：

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

3. 提问

“在 QRZ 上查询 W1AW——他们的网格和执照等级是什么？”

“VP8PJ 属于哪个 DXCC 实体？”

“我的 QRZ 日志里有多少个 QSO？”

“显示我今年 QRZ 日志中所有 20m FT8 的 QSO”

速率限制

QRZ 会执行未公开的速率限制，可能导致 24 小时 IP 封禁。qrz-mcp 会为你提供保护：

• 所有 API 调用之间至少间隔 500ms
• 令牌桶：每分钟 35 个请求
• 身份验证失败后冻结 60s
• 连接被拒绝后冻结 3600s（检测 IP 封禁）
• 内存响应缓存（呼号缓存 5 分钟，DXCC 缓存 1 小时）

无凭据测试

设置 mock 环境变量，即可在没有 QRZ 凭据的情况下测试全部 6 个工具：

QRZ_MCP_MOCK=1 qrz-mcp

MCP Inspector

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

然后在 http://localhost:8002 打开 MCP Inspector。

开发

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

QRZ 订阅等级

功能	免费版	XML 数据（$35.95/年）
每日呼号查询次数	100	不限
返回字段	仅姓名和地址	全部（网格、经纬度、DXCC、等级、QSL、图片）
日志簿 API	否	是
DXCC 查询	否	是

许可证

GPL-3.0-or-later