sota-mcp¶

MCP server for Summits on the Air (SOTA) — live spots, activation alerts, summit info, and nearby summits through any MCP-compatible AI assistant.

Part of the QSO-Graph project. No authentication required — uses the public SOTA API exclusively.

Install¶

uvx sota-mcp            # run it; nothing to install

Tools¶

Tool	Description
`sota_spots`	Current and recent spots with time window and association/mode filters
`sota_alerts`	Upcoming scheduled activation alerts
`sota_summit_info`	Summit details by SOTA reference code
`sota_summits_near`	Find summits near coordinates (geospatial search)
`get_version_info`	Service version + upstream spec version (fleet identity attestation)

Quick Start¶

No credentials needed — just install and configure your MCP client.

Configure your MCP client¶

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

Claude Desktop¶

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

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

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"What SOTA spots are active right now?"

"Tell me about summit W7I/SI-001"

"What summits are near Boise, Idaho?"

"Any SOTA alerts for this weekend?"

Testing Without Network¶

For testing all tools without hitting the SOTA APIs:

SOTA_MCP_MOCK=1 sota-mcp

MCP Inspector¶

sota-mcp --transport streamable-http --port 8007

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

Development¶

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

License¶

GPL-3.0-or-later

Tool Reference¶

Generated from the released server's own tool definitions.

get_version_info¶

Get sota-mcp service version and upstream spec version.

Returns the running PyPI version of sota-mcp and the SOTA api2 endpoint contract in use. Use this to confirm fleet alignment across MCP deployments — agents can compare service_version and spec_version across servers to detect drift without going outside the MCP protocol.

No parameters.

sota_alerts¶

Get upcoming SOTA activation alerts.

Parameter	Type	Required	Default	Description
`hours`	integer	No	`16`	Look-ahead window in hours (default 16).
`association`	string	No	`""`	Filter by SOTA association (e.g., W7I). Empty for all.

sota_spots¶

Get current and recent SOTA spots.

Returns live spot feed with summit details.

Parameter	Type	Required	Default	Description
`hours`	integer	No	`24`	Time window in hours (default 24).
`association`	string	No	`""`	Filter by SOTA association (e.g., W7I, G, VK). Empty for all.
`mode`	string	No	`""`	Filter by mode (e.g., CW, SSB, FT8). Empty for all.

sota_summit_info¶

Get detailed summit information by SOTA reference code.

Parameter	Type	Required	Default	Description
`summit_code`	string	Yes		SOTA reference (e.g., W7I/SI-001, G/LD-001).

sota_summits_near¶

Find SOTA summits near a geographic location.

Parameter	Type	Required	Default	Description
`latitude`	number	Yes		Center latitude (decimal degrees).
`longitude`	number	Yes		Center longitude (decimal degrees).
`radius_km`	number	No	`50.0`	Search radius in km (default 50).
`limit`	integer	No	`20`	Maximum number of results (default 20).