guru

Windguru CLI + MCP + Python library. Same idea as fli: reverse-engineered JSON, zero HTML scraping, agent-first.

Free only — named spots + WINDGURU DEFAULT Tune top-3. No PRO lat/lon click-forecast.

Install

# CLI (recommended)
pipx install windguru

# CLI + MCP server
pipx install 'windguru[mcp]'

guru --help
guru instruct --json

Until the PyPI release is live, install from GitHub:

pipx install 'windguru @ git+https://github.com/berendgort/guru.git'
pipx install 'windguru[mcp] @ git+https://github.com/berendgort/guru.git'

PyPI name windguru, command guru, MCP guru-mcp.

Or with pip:

pip install windguru
pip install 'windguru[mcp]'

MCP Server

pipx install 'windguru[mcp]'

# STDIO (Cursor / Claude Desktop)
guru-mcp

# HTTP (streamable)
guru-mcp-http  # http://127.0.0.1:8000/mcp/

Connecting to Claude Desktop / Cursor

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

Tip: if the binary is not on PATH, use the full path from which guru-mcp (often ~/.local/bin/guru-mcp).

MCP tools

Agent recipe

guru instruct --json
guru spots "castelldefels" --json
guru best 201 --json
guru near --lat 51.9 --lon 4.1 --json
guru best 48309 -H 24 --json   # De Slufter

guru best always uses WINDGURU_DEFAULT Tune weights and returns the top 3 models + forecasts. Prefer that over raw GFS.

JSON envelope: {"ok": true|false, "api_version": 1, "data"|error fields}. Shared error_type / retryable with MCP.

CLI

Ambiguous names fail with error_type: ambiguous + candidates (pass numeric id or --pick).

Library

from guru import search_spots, get_best_forecast, spots_near

spots = search_spots("castelldefels")
best = get_best_forecast(201, top=3, hours=24)
print(best.models[0].name, best.models[0].weight_pct)
print(best.forecasts[0].hours[0].wind_kn)

Architecture

Read AGENTS.md before extending. Capture Network → fixtures → tests.

Engineering standards (kept in-repo):

• docs/code_quality.md — Korotkevich / Tourist bar (layers, size caps, pure core)
• docs/data_engineering_standards.md — Gray / Stonebraker bar (one writer, clocks, contracts)

Disclaimer

Unofficial. Not affiliated with Windguru. Personal / research use; respect ToS and rate limits.

License

MIT