au-weather-mcp

Return current air-quality readings for any Australian location. Sourced from Open-Meteo's air-quality API, which merges Copernicus CAMS European + global air-composition models. Returns PM2.5, PM10, ozone, nitrogen dioxide, sulphur dioxide, carbon monoxide (all µg/m³), plus the European and US AQI indices with plain-English labels. Especially useful during AU bushfire season (Oct–Mar) when smoke can push PM2.5 above safe levels across whole regions. Examples: # Current Sydney air quality resp = await air_quality("sydney") # resp.current.pm2_5_ugm3 == 8.8 # resp.current.european_aqi == 21 # resp.current.european_aqi_label == 'Good' # resp.current.us_aqi == 39 # resp.current.us_aqi_label == 'Good' # Bushfire smoke check for the Blue Mountains resp = await air_quality("-33.7,150.3") # Brisbane CBD via postcode resp = await air_quality("4000") When to use: - "Is the air clean enough to go for a run in <city>?" - Bushfire smoke or burn-off impact checks - Asthma / allergy planning - Long-term air quality monitoring (call periodically and chart) Returns: AirQualityResponse with `current` populated (pollutants + AQI scales), plus location metadata, source_url, attribution, and server_version.

Compare current weather across multiple Australian locations in one call. Fans out concurrently via asyncio.gather, so all locations come back in roughly the time of a single call (after the cache is warm). Each location is independently resolved (curated / state / postcode / geocode / etc.) and independently fetched. If one location fails (e.g. geocoder can't find it), that row gets an `error` field while the rest still return. Examples: # Capital-city dashboard resp = await compare_locations(["sydney","melbourne","brisbane","perth"]) for row in resp.locations: print(row.location_name, row.current.temperature_c) # Tropical north today resp = await compare_locations(["Cairns","Darwin","Townsville","Broome"]) # Mixed input shapes work resp = await compare_locations(["sydney","NSW","2026","-33.87,151.21"]) When to use: - "Compare weather in <several cities>" — the canonical use case - Build a multi-region dashboard in one tool call - Plan a holiday across regions Returns: ComparisonResponse with one ComparisonRow per input location. Successful rows have `current` populated; failed rows have `error`.

Return metadata for an Australian location — name, lat/lng, timezone, elevation, and (for curated locations) the nearest BOM station ID. Accepts a wide range of input shapes for compatibility — see the `location` parameter description. The returned `id` is None for non-curated lookups (geocoded place names, raw coordinates) and a snake_case curated key when the input matched the curated set. Examples: await describe_location("sydney") # → curated path await describe_location("Sydney") # → curated path (case-insensitive) await describe_location("NSW") # → state capital (Sydney) await describe_location("Margaret River") # → geocoded (Western Australia) await describe_location("-33.87,151.21") # → raw coordinates When to use: - Before calling get_weather, to confirm coordinates and timezone - To cross-reference with BOM's own observation network (for curated) - To verify how the server resolved an ambiguous customer input Returns: LocationDetail with id (or None), name, state, lat/lng, timezone, elevation, nearest BOM station ID (curated only), the Open-Meteo URL, and the CC-BY attribution.

Query weather over a date range. Routes to historical archive or forecast endpoint automatically based on the date range. Routing logic: - end_date in the past (>= 5 days ago) → historical archive (1940+) - start_date in the future → forecast (today + 16 days max) - range straddles today → forecast with past_days set Examples: # Historical: how was Sydney summer 2020? resp = await get_weather( "sydney", start_date="2020-01-01", end_date="2020-01-31", granularity="daily", ) # → 31 DailyAggregate rows with temp_max, temp_min, precip per day # 7-day forecast for Melbourne, hourly detail resp = await get_weather( "melbourne", start_date="2026-05-12", end_date="2026-05-19", granularity="hourly", ) # → 168 hourly WeatherObservation rows # Just today (omit both dates) resp = await get_weather("brisbane") # → today's daily aggregate When to use: - Time-series queries (forecast over the next week, or historical comparison) - Multi-day weather analysis - Climate research and historical look-backs (decade-scale via archive) Returns: WeatherResponse with either `daily` or `hourly` populated depending on `granularity`. Period bounds populated from actual returned data.

Return the current weather observation for any Australian location. Wraps Open-Meteo's `/forecast` endpoint with `current=...` parameters and a 15-minute cache TTL (matches Open-Meteo's own update cadence). Use for "what's the weather right now?" — warm-cache latency < 100 ms. Examples: resp = await latest("sydney") # curated, fast path resp = await latest("Sydney") # case-insensitive resp = await latest("Byron Bay") # geocoded resp = await latest("NSW") # state → Sydney resp = await latest("-33.87,151.21") # raw coordinates The response's `location_resolution` field tells the agent how the input was interpreted ('curated', 'state_alias', 'geocoded', 'raw_coordinates', or 'fuzzy_curated'). When to use: - "What's the weather right now in <place>?" — canonical use case - Multi-city current-conditions dashboards (call once per place) - Anchoring agent conversations to live weather context Returns: WeatherResponse with `current` populated, plus location metadata, resolution source, source_url, CC-BY attribution, and server_version.

List the 45 curated Australian location IDs supported by this MCP. The curated set covers all 8 state/territory capitals plus 37 major regional centres. Any Australian place name outside this set still works via the place-name geocoder; the curated entries just get fast-path lookup (no network call) and appear in `search_locations`. Coverage by state: - 8 capitals: sydney, melbourne, brisbane, perth, adelaide, hobart, darwin, canberra - NSW regional (10): newcastle, wollongong, tamworth, wagga_wagga, albury, orange, bathurst, dubbo, coffs_harbour, port_macquarie - VIC regional (6): geelong, ballarat, bendigo, mildura, shepparton, warrnambool - QLD regional (9): gold_coast, sunshine_coast, cairns, townsville, mackay, toowoomba, rockhampton, bundaberg, hervey_bay - WA regional (5): broome, bunbury, geraldton, albany, kalgoorlie - SA regional (2): mount_gambier, whyalla - TAS regional (3): launceston, devonport, burnie - NT regional (2): alice_springs, katherine When to use: - You want to enumerate which locations have first-class support - You're building a UI / dashboard that needs the supported set up front - You want to plan a multi-location dashboard call Returns: Sorted list of location IDs (currently 45). Adding a location is a YAML edit in src/au_weather_mcp/data/curated/locations.yaml.

Fuzzy-search the 45 curated Australian locations. The curated set covers all 8 state/territory capitals plus 37 major regional centres (every AU population centre over ~25k). Anything outside the curated set still resolves via place-name geocoding or postcode lookup — see `list_curated()` for the full set. Examples: results = await search_locations("sydney") # → [{id: 'sydney', name: 'Sydney', state: 'NSW', ...}] results = await search_locations("nsw") # → Newcastle, Wollongong, Sydney (all NSW locations) When to use: - Discover the location ID for a city you know by name - Find all supported locations in a state - Verify whether a place is in the curated set before calling get_weather Returns: List of LocationSummary (id, name, state, description), ranked by relevance.