wspr-mcp¶

MCP server for WSPR (Weak Signal Propagation Reporter) beacon data — live spots, band activity, top beacons, propagation paths, SNR trends, and more through any MCP-compatible AI assistant.

Data from wspr.live (~2.7 billion spots, 2008-present). Part of the qso-graph project. No authentication required — all public data.

Install¶

uvx wspr-mcp            # run it; nothing to install

Tools¶

Tool	Description	Key Parameters
`wspr_spots`	Recent WSPR spots with flexible filtering	callsign, band, hours, grid, min/max SNR, min distance
`wspr_band_activity`	Per-band spot counts, station counts, distances, and SNR	hours
`wspr_top_beacons`	Top transmitters ranked by spot count or max distance	band, hours, sort_by (spots/distance), limit
`wspr_top_spotters`	Top receivers ranked by spot count or max distance	band, hours, sort_by (spots/distance), limit
`wspr_propagation`	Propagation between two locations — auto-widens to field-level proxy for sparse endpoints	tx, rx, band, hours
`wspr_grid_activity`	All WSPR activity in/out of a Maidenhead grid square	grid (2 or 4 char), band, hours
`wspr_longest_paths`	Longest distance WSPR paths in a time window	band, hours, min_distance, limit
`wspr_snr_trend`	Hourly SNR trend for a specific path over time	tx, rx, band, hours
`get_version_info`	Service version + upstream spec version (fleet identity attestation)	—

What is WSPR?¶

WSPR beacons transmit a 2-minute encoded signal at very low power (typically 200 mW to 5 W). Each decoded spot proves a propagation path exists between two locations on a specific band. With thousands of beacons worldwide transmitting 24/7, WSPR provides continuous, automated propagation monitoring across all HF bands.

Good Neighbour Policy¶

wspr.live is a volunteer-run service that mirrors all wsprnet.org data into a public ClickHouse database. We take our responsibility as a good neighbour seriously:

Measure	Detail
Rate limiting	3 seconds between requests (20 req/min max)
Circuit breaker	Opens after 3 consecutive failures; exponential backoff up to 5 minutes. Prevents hammering a struggling service.
Time-bounded queries	Every query filters by time (max 72 hours). No unbounded full-table scans.
Band filtering	Queries filter by band whenever the user provides one — this hits wspr.live's indexes efficiently.
Column selection	We SELECT only the columns each tool needs (8-10 per query), never `SELECT *`.
Result limits	All queries cap results (200 spots, 50 leaderboard entries).
Response caching	2-10 minute TTL per tool. Identical queries within the window hit local cache with zero network traffic.
Request timeout	20-second timeout — we don't hold connections open on a shared service.
User-Agent header	Every request identifies itself as `wspr-mcp/{version}` so the operators can reach us if needed.

If wspr.live is down or overloaded, the circuit breaker backs off automatically. We don't retry in a tight loop.

Quick Start¶

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

Configure your MCP client¶

Claude Desktop¶

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

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

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"Show me recent WSPR spots on 20m"

"What bands are open right now?"

"Who are the top WSPR beacons on 20m today?"

"What are the longest WSPR paths in the last 24 hours?"

"Is there propagation between Idaho (DN13) and central Europe (JN48)?"

"Any WSPR paths between DN13 and Bouvet (JD15)?" (auto-widens to DN↔JD if no exact match)

"What's happening in grid square JN48?"

"How's the SNR trending between K9AN and G8JNJ on 20m?"

"Who are the best WSPR receivers sorted by distance?"

Testing Without Network¶

WSPR_MCP_MOCK=1 wspr-mcp

MCP Inspector¶

wspr-mcp --transport streamable-http --port 8009

Development¶

git clone https://github.com/qso-graph/wspr-mcp.git
cd wspr-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 wspr-mcp service version and upstream spec version.

Returns the running PyPI version of wspr-mcp and the wspr.live ClickHouse schema revision 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.

wspr_band_activity¶

Get per-band WSPR activity summary.

Shows spot counts, TX/RX station counts, average and max distance, and average SNR for each band. The best indicator of which bands are open right now.

Parameter	Type	Required	Default	Description
`hours`	integer	No	`1`	Time window in hours (1-6, default 1).

wspr_grid_activity¶

Get all WSPR activity in or out of a Maidenhead grid square.

Shows summary stats and recent spots for a geographic area. Use 2-character grid (e.g., DN) for a wide area or 4-character (e.g., DN13) for a specific region.

Parameter	Type	Required	Default	Description
`grid`	string	Yes		Maidenhead grid square — 2 char (DN) or 4 char (DN13).
`band`	string	No	`""`	Filter by band (e.g., 20m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).
`limit`	integer	No	`50`	Maximum recent spots to return (1-200, default 50).

wspr_longest_paths¶

Get the longest WSPR paths in the given time window.

WSPR's precise timing and low power make it the gold standard for detecting marginal propagation. Long paths here prove the band is open.

Parameter	Type	Required	Default	Description
`band`	string	No	`""`	Filter by band (e.g., 20m, 10m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).
`limit`	integer	No	`20`	Maximum paths to return (1-50, default 20).
`min_distance`	integer	No	`0`	Minimum distance in km (e.g., 15000 for near-antipodal).

wspr_propagation¶

Get WSPR-derived propagation between two locations.

Shows which bands have been open between two endpoints, with spot counts, SNR statistics, and hours of opening. Accepts callsigns or grid squares (or a mix). Searches both directions automatically.

Parameter	Type	Required	Default	Description
`tx`	string	Yes		First endpoint — callsign (e.g., KI7MT) or grid (e.g., DN13).
`rx`	string	Yes		Second endpoint — callsign (e.g., G8JNJ) or grid (e.g., IO91).
`band`	string	No	`""`	Filter to a specific band (e.g., 20m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).

wspr_snr_trend¶

Get SNR trend over time for a specific WSPR path.

Shows hourly SNR buckets for a path between two endpoints. Useful for seeing when a band opens and closes on a specific path, and how signal strength varies over time.

Parameter	Type	Required	Default	Description
`tx`	string	Yes		First endpoint — callsign (e.g., K9AN) or grid (e.g., EN50).
`rx`	string	Yes		Second endpoint — callsign (e.g., G8JNJ) or grid (e.g., IO91).
`band`	string	No	`""`	Filter to a specific band (e.g., 20m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).

wspr_spots¶

Get recent WSPR spots.

WSPR beacons transmit every 2 minutes on precise frequencies. Each spot is a 2-minute integration proving a propagation path exists.

Parameter	Type	Required	Default	Description
`callsign`	string	No	`""`	Filter by TX or RX callsign (e.g., KI7MT, K9AN). Empty for all.
`band`	string	No	`""`	Filter by band (e.g., 20m, 40m, 10m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).
`limit`	integer	No	`50`	Maximum spots to return (1-200, default 50).
`grid`	string	No	`""`	Filter by grid square prefix (e.g., DN13, FN31). Matches TX or RX.
`min_snr`	integer	No	`null`	Minimum SNR in dB (e.g., -20). Filter out weak signals.
`max_snr`	integer	No	`null`	Maximum SNR in dB (e.g., -5). Filter out strong signals.
`min_distance`	integer	No	`null`	Minimum path distance in km (e.g., 5000 for DX only).

wspr_top_beacons¶

Get top WSPR transmitters ranked by spot count or max distance.

Shows the most active or most far-reaching WSPR beacon operators. Useful for finding who's putting out a big signal on a band.

Parameter	Type	Required	Default	Description
`band`	string	No	`""`	Filter by band (e.g., 20m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).
`sort_by`	string	No	`"spots"`	Ranking criteria — "spots" (most heard) or "distance" (farthest reach).
`limit`	integer	No	`20`	Number of results (1-50, default 20).

wspr_top_spotters¶

Get top WSPR receivers ranked by spot count or max distance.

Shows the most prolific or most sensitive WSPR receiving stations. Useful for finding good receivers to monitor for propagation.

Parameter	Type	Required	Default	Description
`band`	string	No	`""`	Filter by band (e.g., 20m). Empty for all bands.
`hours`	integer	No	`24`	Time window in hours (1-72, default 24).
`sort_by`	string	No	`"spots"`	Ranking criteria — "spots" (most received) or "distance" (farthest heard).
`limit`	integer	No	`20`	Number of results (1-50, default 20).