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 のバージョン（フリート ID の証明）

クイックスタート

1. 認証情報を設定する

qrz-mcp は認証情報の管理に qso-graph-auth のペルソナを使用します。QRZ には2 種類の独立した認証方式があり、それぞれプロバイダーとして公開されています。必要なものを設定してください。

プロバイダー	ツール	認証情報
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）を指定します。

--password / --api-key を省略すると、代わりに入力を求められます。シークレットを CLI 引数として渡すと、シェルの履歴に残ります。

XML API（コールサイン検索、DXCC）には QRZ XML サブスクリプション（年額 $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 の下に追加するか、エージェント定義で設定します。

{
  "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 リクエスト
• 認証失敗時は 60 秒間停止
• 接続拒否時は 3600 秒間停止（IP 禁止の検出）
• メモリ内レスポンスキャッシュ（コールサインは 5 分、DXCC は 1 時間）

認証情報なしでのテスト

モック環境変数を設定すると、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/年）
1日あたりのコールサイン検索数	100	無制限
返されるフィールド	名前と住所のみ	すべて（グリッド、緯度/経度、DXCC、クラス、QSL、画像）
ログブックAPI	いいえ	はい
DXCC検索	いいえ	はい

ライセンス

GPL-3.0-or-later