clublog-mcp

MCP server for Club Log — DXCC entity resolution, expedition log search, propagation activity, Most Wanted rankings, and real-time callsign monitoring through any MCP-compatible AI assistant.

Part of the qso-graph project. Operated by Michael Wells, G7VJR.

Install

pip install clublog-mcp

Tools

Quick Start

1. Get an API key

Request an application API key at clublog.org/requestapikey.php. This is a per-application key (40-character hex), not a per-user credential.

Important: API keys are auto-revoked if found in public repos (GitHub scanning active).

2. Set the environment variable

export CLUBLOG_API_KEY=your-40-char-hex-key

Two tools (clublog_most_wanted and clublog_expeditions) work without an API key.

3. Configure your MCP client

Claude Desktop

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

{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

ChatGPT Desktop

{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

VS Code / GitHub Copilot

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

{
  "servers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

Gemini CLI

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

{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}

4. Ask questions

"What DXCC entity is 3Y0J?"

"Am I in the 3Y0J expedition log? Search for KI7MT"

"Show me propagation activity between USA (291) and Japan (339)"

"What are the top 10 Most Wanted DXCC entities?"

"What expeditions are currently active on Club Log?"

"Is 3Y0J still on the air? Show me their 24-hour activity"

Rate Limiting

Club Log has no published rate limits, but enforcement is real and automatic. clublog-mcp protects you:

• 500ms minimum delay between all API calls
• Token bucket: 30 requests/minute
• 3600s freeze on HTTP 403 (IP ban detection)
• Response caching (DXCC: 1hr, Most Wanted: 24hr, Activity: 1hr, Watch: 5min)

Never loop over /dxcc for batch resolution — Club Log provides /bulkdxcc for that (future v2.0 feature).

Band Normalization

Club Log uses bare numbers for bands. clublog-mcp normalizes all responses to ADIF names:

Testing Without an API Key

Set the mock environment variable to test all 6 tools:

CLUBLOG_MCP_MOCK=1 clublog-mcp

MCP Inspector

CLUBLOG_API_KEY=your-key clublog-mcp --transport streamable-http --port 8003

Development

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

License

GPL-3.0-or-later