Eqsl MCP server

<!-- mcp-name: io.github.qso-graph/eqsl-mcp -->

eqsl-mcp

MCP server for eQSL.cc — download incoming eQSLs, verify QSOs, check AG status, and query upload history through any MCP-compatible AI assistant.

Part of the qso-graph project. Uses qso-graph-auth for credential management.

Install

pip install eqsl-mcp

Tools

Quick Start

1. Set up credentials

eqsl-mcp uses qso-graph-auth personas for credential management:

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

# Create a persona and add eQSL credentials
qso-auth persona create ki7mt --callsign KI7MT
qso-auth persona provider ki7mt eqsl --username KI7MT
qso-auth persona secret ki7mt eqsl

2. Configure your MCP client

eqsl-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.

Claude Desktop

Add to claudedesktopconfig.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

ChatGPT Desktop

ChatGPT supports MCP via the OpenAI Agents SDK. Add under Settings > Apps & Connectors, or configure in your agent definition:

{
  "mcpServers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

VS Code / GitHub Copilot

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

{
  "servers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

Gemini CLI

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

{
  "mcpServers": {
    "eqsl": {
      "command": "eqsl-mcp"
    }
  }
}

3. Ask questions

"Show me all eQSLs received this week"

"How many unconfirmed eQSLs do I have on 20m FT8?"

"Does W1AW have AG status on eQSL?"

"Verify my QSO with KI7MT on 20m on March 1, 2026"

Testing Without Credentials

The two public tools (eqslverify and eqslag_check) work without any credentials.

For eqsl_inbox testing, set the mock environment variable:

EQSL_MCP_MOCK=1 eqsl-mcp

Or point to a local ADIF file:

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

MCP Inspector

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

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

Development

git clone https://github.com/qso-graph/eqsl-mcp.git
cd eqsl-mcp
pip install -e .

Date Formats

eQSL uses different date formats across endpoints. eqsl-mcp normalizes everything — you always use YYYY-MM-DD:

Mode Matching

eQSL requires exact mode matching. SSB won't match USB/LSB. PSK won't match PSK31. Use the exact mode logged by the other station.

License

GPL-3.0-or-later