eqsl-mcp

eqsl-mcp

eQSL.cc 用の MCP サーバーです。MCP 対応の AI アシスタントから、受信した eQSL のダウンロード、QSO の確認、AG ステータスの確認、アップロード履歴の照会ができます。

qso-graph プロジェクトの一部です。認証情報の管理には qso-graph-auth を使用します。

インストール

uvx eqsl-mcp            # run it; nothing to install

ツール

ツール	認証	説明
eqsl_inbox	はい	日付や確認状況で絞り込んで、受信した eQSL をダウンロードします
eqsl_verify	いいえ	指定した QSO が eQSL に存在するか確認します
eqsl_ag_check	いいえ	コールサインが AG（Authenticity Guaranteed）ステータスか確認します
eqsl_download	はい	ロガーにインポートできるよう、eQSL の受信箱を生 ADIF 形式でダウンロードします
eqsl_last_upload	いいえ	ペルソナが最後に eQSL へアップロードした日時を確認します
get_version_info	いいえ	サービスのバージョンと、上流の eQSL.cc エンドポイントのバージョン（フリートの識別情報の証明）を確認します

クイックスタート

1. 認証情報を設定する

eqsl-mcp は、認証情報の管理に qso-graph-auth のペルソナを使用します。

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

# A persona (your callsign and the dates it covers), then eQSL for it
qso-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-auth provider enable ki7mt eqsl
qso-auth creds set ki7mt eqsl      # asks for your username, then your password (hidden)

3 つの手順すべてが必要です。provider enable を実行しないと、サーバーはペルソナに eqsl ref がないと報告します。

2. MCP クライアントを設定する

eqsl-mcp は、MCP 対応のクライアントであればどれでも使用できます。サーバー設定を追加して再起動すると、ツールが自動的に表示されます。

Claude Desktop

claude_desktop_config.json に追加します（macOS では ~/Library/Application Support/Claude/、Windows では %APPDATA%\Claude\）。

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

Claude Code

.claude/settings.json に追加します。

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

ChatGPT Desktop

ChatGPT は OpenAI Agents SDK 経由で MCP をサポートしています。Settings > Apps & Connectors で追加するか、エージェント定義で設定します。

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

Cursor

.cursor/mcp.json（プロジェクトレベル）または ~/.cursor/mcp.json（グローバル）に追加します。

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

VS Code / GitHub Copilot

ワークスペース内の .vscode/mcp.json に追加します。

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

Gemini CLI

~/.gemini/settings.json（グローバル）または .gemini/settings.json（プロジェクト）に追加します。

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

3. 質問する

「今週受信した eQSL をすべて表示して」

「20m FT8 で未確認の eQSL はいくつありますか？」

「W1AW は eQSL で AG ステータスですか？」

「2026 年 3 月 1 日の 20m での KI7MT との QSO を確認して」

認証情報なしでのテスト

公開ツールの eqsl_verify と eqsl_ag_check は、認証情報なしで動作します。

eqsl_inbox をテストするには、モック環境変数を設定します。

EQSL_MCP_MOCK=1 eqsl-mcp

または、ローカルの ADIF ファイルを指定します。

EQSL_MCP_MOCK=1 EQSL_MCP_ADIF=/path/to/test.adi eqsl-mcp

MCP Inspector

eqsl-mcp --transport streamable-http --port 8001

その後、http://localhost:8001 で MCP Inspector を開きます。

開発

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

日付形式

eQSL では、エンドポイントによって異なる日付形式が使用されます。eqsl-mcp はすべての形式を正規化するため、常に YYYY-MM-DD を使用します。

指定する値	eqsl-mcp が送信する値	エンドポイント
2026-03-01	202603010000	DownloadInBox (RcvdSince)
2026-03-01	03/01/2026	VerifyQSO (QSODate)

モードの照合

eQSL ではモードの完全一致が必要です。SSB は USB／LSB と一致しません。PSK は PSK31 と一致しません。相手局が記録した正確なモードを使用してください。

既知の注意点

• AG リストのキャッシュ： Authenticity Guaranteed のメンバーリストは4時間キャッシュされます（eQSL は1日に約6回更新します）。保存先は ~/.cache/eqsl-mcp/ag_members.txt です（$XDG_CACHE_HOME が設定されている場合はそのディレクトリ、Windows では %LOCALAPPDATA%\eqsl-mcp\）。
• 受信トレイのダウンロード： eQSL は .adi ファイルへのリンクを含む HTML ページを返すため、受信トレイは2段階で取得します。eQSL が ADIF を直接返す場合は、そのまま使用します。

ライセンス

GPL-3.0-or-later