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	否	检查 eQSL 中是否存在指定的 QSO
eqsl_ag_check	否	检查某个呼号是否具有 AG（真实性保证）状态
eqsl_download	是	将你的 eQSL 收件箱下载为原始 ADIF，以便导入到你的日志软件
eqsl_last_upload	否	查询某个 persona 最近一次向 eQSL 上传的时间
get_version_info	否	服务版本及上游 eQSL.cc 端点版本（集群身份认证）

快速开始

1. 设置凭据

eqsl-mcp 使用 qso-graph-auth persona 管理凭据：

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

这三个步骤都必不可少：如果未运行 provider enable，服务会报告该 persona 没有 eqsl 引用。

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 下添加，或在 Agent 定义中配置：

{
  "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 日与 KI7MT 在 20m 上进行的 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 每天更新约六次），缓存文件位于 ~/.cache/eqsl-mcp/ag_members.txt（若设置了 $XDG_CACHE_HOME，则使用该目录；Windows 上为 %LOCALAPPDATA%\eqsl-mcp\）。
• 收件箱下载： eQSL 返回的 HTML 页面中包含指向 .adi 文件的链接，因此收件箱分两步获取。如果 eQSL 直接返回 ADIF，则直接使用。

许可证

GPL-3.0-or-later