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

pipx install windguru
guru --help

Need MCP (Cursor / Claude Desktop)?

pipx install 'windguru[mcp]'
guru-mcp

Or with pip: pip install windguru / pip install 'windguru[mcp]'.

PyPI: windguru · commands: guru, guru-mcp, guru-mcp-http

Quick start (Cursor / agents)

First pass — agent shows one prompt; user pastes one line:

sport=kitefoil weight=78 level=intermediate kites=7,9,12 wetsuits=3/2,4/3 session=3 home=41.39,2.17 drive_km=200 range=Trabucador → Leucate

guru setup --intake '<paste>' --json
guru weekend --json
guru best 201 --advise --json

guru instruct --json / guru profile --json expose intake.prompt_to_user when the profile is incomplete — agents must ask once, not field-by-field.

MCP (Cursor / Claude Desktop)

pipx install 'windguru[mcp]'
guru-mcp          # STDIO
guru-mcp-http     # http://127.0.0.1:8000/mcp/

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

If needed, use the full path from which guru-mcp (often ~/.local/bin/guru-mcp).

More: docs/mcp.md.

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)

Develop

git clone https://github.com/berendgort/guru.git
cd guru
pipx install -e ".[dev,mcp]"
# or: python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev,mcp]"
pytest -q
ruff check .

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

Engineering standards (kept in-repo):

• docs/code_quality.md — Korotkevich / Tourist bar
• docs/data_engineering_standards.md — Gray / Stonebraker bar

Disclaimer

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

License

MIT