Tools

Five tools covering aviation weather — station lookup, current observations, terminal forecasts, pilot reports, and active advisories:

aviation_find_stations

Resolve and discover weather stations by multiple search modes.

• Look up one or more stations by 4-letter ICAO ID (up to 20 IDs per call) — lookup is ICAO-only, but each returned record includes its IATA/FAA aliases when available
• Discover all stations within a geographic bounding box
• List stations for one of the 50 US states or DC via two-letter USPS code (uses bbox + client-side state filter)
• Returns data_types (METAR, TAF, etc.) so agents can confirm what's available before querying
• Every result states whether the upstream 400-row cap cut it, so a truncated draw is never mistaken for every station in the area — a capped state query also reports the row count from before the state filter, and a smaller bbox is the named lever

aviation_get_metar

Fetch current or recent METAR observations (1–10 stations per call).

• hours parameter (1–12) returns observation history per station; default 1 returns only the most recent
• Flight category (VFR/MVFR/IFR/LIFR) is returned directly from the AWC API — no client-side computation needed
• Decodes cloud layers, wind with gusts, visibility, and present weather (the raw groups plus plain English, one reading per group) in addition to the raw METAR string
• Ceiling covers broken, overcast, and obscuration layers, and reports whether the height was measured or is an indefinite ceiling — vertical visibility into an obscuration
• METAR type field distinguishes METAR (routine) from SPECI (special observation triggered by significant weather change)
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

aviation_get_taf

Fetch Terminal Aerodrome Forecasts for 1–4 airports.

• Returns structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities
• Forecast weather decoded group by group beside the raw groups (-SHRA BR → light rain showers; mist), the same shape aviation_get_metar returns
• Forecast obscurations keep their layer and carry the vertical visibility into them (VV002 → a 200 ft indefinite ceiling), rather than reading as a clear sky
• Low-level wind shear (WS020/20040KT) is decoded to the shear-layer top and the forecast wind at that height
• valid_from / valid_to in ISO 8601 for straightforward time comparisons
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

aviation_get_pireps

Search for recent Pilot Reports by station+radius or bounding box.

• station_id + distance_nm (10–500 nm, 100 when omitted) for radial search around an airport
• bbox for geographic area search — useful for en-route corridor checks; distance_nm has no meaning here and is rejected alongside it
• altitude_min_ft / altitude_max_ft filters to isolate reports at cruise altitude, either bound alone or both (min must not exceed max)
• Turbulence and icing arrays include up to two layers per report (as reported by the API)
• Every result states whether the upstream 400-row cap cut it, naming bbox, distance_nm, and hours as the levers that narrow a query before the cap applies — the altitude filter runs after it and cannot recover a dropped report
• Note: absence of PIREPs does not mean smooth conditions — they are sparse by nature

aviation_get_advisories

List currently active domestic SIGMETs.

• advisory_type filter: sigmet or all (default) — both return the active SIGMET set
• hazard filter: CONVECTIVE, TURBULENCE, ICING, IFR
• bbox filter applied client-side (AWC API returns all active advisories; the tool filters by polygon overlap)
• AIRMETs are not served. The upstream feed carries domestic SIGMETs only, so advisory_type: airmet and the MTN OBSCN, SURFACE WIND, and LLWS hazards are rejected with guidance rather than answered with SIGMETs or an empty array
• During fair-weather periods, no SIGMETs may be active — an empty result is a valid state, not an error

Prompts

All resource data is reachable via tools. This server has no resources — all aviation weather data is time-sensitive (METARs valid ~1 hour, advisories minutes to hours) and unsuitable for stable-URI resources.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Aviation-weather-specific:

• Keyless — no API key or authentication required; all data is from the public AWC Data API
• Single service (aviation-weather-service) with retry + exponential backoff for the keyless public endpoint
• Raw coded strings (rawOb, rawTAF, rawAirSigmet) surfaced alongside decoded fields so agents have both layers
• State→bbox table enables US-state station queries that the AWC API doesn't natively support
• Server-level instructions field surfaces the "not an official briefing" safety disclaimer to all clients on initialize

Agent-friendly output:

• Flight category (VFR/MVFR/IFR/LIFR) as a discriminated string field — agents can branch on it without parsing ceiling + visibility
• Structured error contracts with typed reason fields and recovery hints (e.g., "Verify ICAO IDs with aviation_find_stations")
• aviation_preflight_brief prompt encodes the correct METAR → TAF → PIREPs → advisories briefing sequence that agents frequently get wrong by omitting steps

Getting started

Public Hosted Instance

A public hosted instance is available at https://aviation-weather.caseyjhand.com/mcp. Add it to your MCP client configuration:

{
  "mcpServers": {
    "aviation-weather": {
      "type": "streamable-http",
      "url": "https://aviation-weather.caseyjhand.com/mcp"
    }
  }
}

Self-hosted / local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/aviation-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/aviation-weather-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/aviation-weather-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• No API key required — the AWC Data API is fully public and keyless.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/aviation-weather-mcp-server.git

2. Navigate into the directory:

cd aviation-weather-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/aviation-weather-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and prompts via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Not an official preflight briefing. Data from the AWC is informational only. Real flight planning requires an authorized source (e.g., Leidos/1800wxbrief.com). The server surfaces this disclaimer via its instructions field sent on every initialize.

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.