Weather Signal

 _       __           __  __                 _____ _                   __
| |     / /__  ____ _/ /_/ /_  ___  _____   / ___/(_)___ _____  ____ _/ /
| | /| / / _ \/ __ `/ __/ __ \/ _ \/ ___/   \__ \/ / __ `/ __ \/ __ `/ /
| |/ |/ /  __/ /_/ / /_/ / / /  __/ /      ___/ / / /_/ / / / / /_/ / /
|__/|__/\___/\__,_/\__/_/ /_/\___/_/      /____/_/\__, /_/ /_/\__,_/_/
                                                 /____/
             Weather context
         for forecasting agents.

Weather Signal is an agent-first weather data CLI and MCP server for turning Open-Meteo forecasts into stable, scriptable demand signals. It is built for forecasting flows that need more than a pretty terminal forecast: consistent JSON, saved business locations, local caching, MCP tools, and demand-friendly features such as rain likelihood, warm days, windy days, sunshine, and UV.

What It Does

• Fetches Open-Meteo forecasts with no key required for local development.
• Resolves city names through Open-Meteo geocoding, with optional country hints.
• Stores saved places so business locations can be referenced by alias.
• Outputs agent-ready JSON by default, plus table and CSV modes.
• Caches responses locally to keep repeated agent runs fast and predictable.
• Adds agent workflow commands for summaries, thresholds, batch locations, historical context, and shell completions.
• Supports commercial endpoints through configurable base URLs and API keys.

30-Second Example

weather-signal signal london --country GB --days 3

Example output shape (abridged):

{
  "source": "open-meteo",
  "location": {
    "name": "London",
    "country_code": "GB",
    "latitude": 51.50853,
    "longitude": -0.12574
  },
  "cache": "miss",
  "profile": "demand",
  "days": [
    {
      "date": "2026-04-27",
      "temp_max_c": 20.4,
      "precip_probability_max_pct": 46,
      "precipitation_mm": 0.1,
      "flags": {
        "rain_likely": false,
        "warm_day": true,
        "sunny_day": true
      }
    }
  ]
}

Installation

curl -fsSL https://raw.githubusercontent.com/joe-broadhead/weather-signal/HEAD/scripts/install.sh | bash

Install the binary and Weather Signal agent skills:

curl -fsSL https://raw.githubusercontent.com/joe-broadhead/weather-signal/HEAD/scripts/install.sh | bash -s -- --install-skills

Prebuilt Binaries

Release assets are published from the GitHub Release workflow with checksums, SBOMs, and provenance attestations.

# macOS Apple Silicon
curl -L -o weather-signal.tar.gz \
  https://github.com/joe-broadhead/weather-signal/releases/download/v0.0.0/weather-signal-macos-arm64.tar.gz

tar -xzf weather-signal.tar.gz
./weather-signal-macos-arm64/weather-signal --version

Choose the asset for your platform from Releases.

From Source

git clone https://github.com/joe-broadhead/weather-signal.git
cd weather-signal
cargo build --locked --release

# Try the main agent signal command
cargo run -- signal london --country GB --days 7

# Human-readable table
cargo run -- daily london --country GB --days 3 --table

# CSV for spreadsheets or feature stores
cargo run -- hourly "51.5072,-0.1276" --hours 24 --output csv

Quick Start

weather-signal signal london --country GB --days 7
weather-signal daily london --country GB --days 3 --table
weather-signal hourly "51.5072,-0.1276" --hours 24 --output csv

CLI Usage

weather-signal geocode <query> [--country GB] [--count 5]
weather-signal places add <alias> <query> [--country GB]
weather-signal places list
weather-signal places remove <alias>
weather-signal current <location>
weather-signal daily <location> [--days 7]
weather-signal hourly <location> [--hours 48]
weather-signal signal <location> [--days 7] [--profile demand]
weather-signal summary <location> [--days 7]
weather-signal threshold <location> --rain-prob-gte 60
weather-signal batch signal --places all
weather-signal historical <location> --start YYYY-MM-DD --end YYYY-MM-DD
weather-signal server start --transport stdio
weather-signal server start --transport streamable-http --http-port 8768
weather-signal completions zsh
weather-signal cache status
weather-signal cache prune --max-age 7d
weather-signal cache clear

Global options:

--output json|table|csv
--table
--refresh
--cache-ttl 30m
--timeout 30s
--api-key <key>
--forecast-base-url <url>
--geocode-base-url <url>
--historical-base-url <url>
--config <path>

Saved Places

Saved places make repeatable business workflows less brittle:

weather-signal places add london "London" --country GB
weather-signal signal london --days 7

Config lives at:

~/.config/weather-signal/config.toml

Cache lives at:

~/.cache/weather-signal

Use weather-signal cache prune --max-age 7d for routine cache maintenance, or weather-signal cache clear when you need to remove every cached response.

Commercial Open-Meteo Usage

The public Open-Meteo endpoint is the default. For commercial or self-hosted usage, configure an API key or endpoint override:

export OPEN_METEO_API_KEY="..."
export OPEN_METEO_FORECAST_BASE_URL="https://customer-api.open-meteo.com/v1/forecast"
export OPEN_METEO_GEOCODING_BASE_URL="https://geocoding-api.open-meteo.com/v1/search"
export OPEN_METEO_HISTORICAL_BASE_URL="https://archive-api.open-meteo.com/v1/archive"

MCP Server

Weather Signal can run as an MCP server over stdio or streamable HTTP:

weather-signal server start --transport stdio
weather-signal server start --transport streamable-http --http-host 127.0.0.1 --http-port 8768 --http-path /mcp

The MCP surface exposes tools such as weather_summary, demand_signal, threshold_days, historical_weather, daily_forecast, and geocode. Streamable HTTP is stateless by default and should stay on loopback unless an authenticating proxy controls access. Use --http-stateful-mode only for trusted local clients because stateful sessions are held in process memory.

Documentation

• Getting Started
• CLI Reference
• MCP Reference
• Signal Reference
• Configuration
• Agent Skills
• Agent Development Guide
• Contributing

Contributing

See CONTRIBUTING.md for development setup, quality gates, documentation checks, and PR expectations.

License

MIT. See LICENSE.