io.github.cyanheads/aviation-weather-mcp-server

Official

by cyanheads · TypeScript

Fetch METARs, TAFs, PIREPs, and SIGMETs/AIRMETs from the NWS Aviation Weather Center.

Fetch aviation weather reports including METARs, TAFs, PIREPs, and SIGMETs.

Topics

ai-agentsai-toolsaviationaviation-weathercyanheadsmcpmcp-servermetarmodel-context-protocolnoaataftypescript

README.md13 KBView on GitHub

<div align="center"> <h1>@cyanheads/aviation-weather-mcp-server</h1> <p><b>Fetch METARs, TAFs, PIREPs, and SIGMETs/AIRMETs from the NWS Aviation Weather Center via MCP. STDIO or Streamable HTTP.</b> <div>5 Tools • 1 Prompt</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://aviation-weather.caseyjhand.com/mcp

</div>

Tools

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

Tool	Description
`aviation_find_stations`	Resolve airports and weather stations by ICAO ID, bounding box, or US state. Returns ICAO/IATA/FAA IDs, coordinates, elevation, and available data types.
`aviation_get_metar`	Get current weather observations (METARs) for one or more airports. Returns decoded wind, visibility, ceiling, temp/dewpoint, altimeter, cloud layers, flight category (VFR/MVFR/IFR/LIFR), and the raw METAR string.
`aviation_get_taf`	Get Terminal Aerodrome Forecasts for one or more airports. Returns each forecast period with valid times, wind, visibility, weather codes, and cloud layers, plus the raw TAF string.
`aviation_get_pireps`	Get recent Pilot Reports near an airport or within a bounding box. Returns decoded turbulence, icing, and cloud reports with altitude, aircraft type, intensity, and the raw PIREP string.
`aviation_get_advisories`	Get active SIGMETs and AIRMETs for a region. Returns hazard type (CONVECTIVE, TURBULENCE, ICING, IFR, MTN OBSCN), severity, altitude range, valid period, polygon coordinates, and raw text.

`aviation_find_stations`

Resolve and discover weather stations by multiple search modes.

Look up one or more stations by ICAO, IATA, or FAA ID (up to 20 IDs per call)
Discover all stations within a geographic bounding box
List stations for a US state via two-letter abbreviation (uses bbox + client-side state filter)
Returns data_types (METAR, TAF, etc.) so agents can confirm what's available before querying

`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, and visibility in addition to the raw METAR string
METAR type field distinguishes METAR (routine) from SPECI (special observation triggered by significant weather change)

`aviation_get_taf`

Fetch Terminal Aerodrome Forecasts for 1–4 airports.

Returns structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities
Common weather codes (e.g., -SHRA, TSRA) decoded to plain English alongside the raw string
valid_from / valid_to in ISO 8601 for straightforward time comparisons

`aviation_get_pireps`

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

station_id + distance_nm (10–500 nm, default 100) for radial search around an airport
bbox for geographic area search — useful for en-route corridor checks
altitude_min_ft / altitude_max_ft filters to isolate reports at cruise altitude
Turbulence and icing arrays include up to two layers per report (as reported by the API)
Note: absence of PIREPs does not mean smooth conditions — they are sparse by nature

`aviation_get_advisories`

List currently active SIGMETs and AIRMETs.

advisory_type filter: sigmet, airmet, or all (default)
hazard filter: CONVECTIVE, TURBULENCE, ICING, IFR, MTN OBSCN, SURFACE WIND, LLWS
bbox filter applied client-side (AWC API returns all active advisories; the tool filters by polygon overlap)
During fair-weather periods, no AIRMETs may be active — an empty result is a valid state, not an error

Prompts

Type	Name	Description
Prompt	`aviation_preflight_brief`	Structure a preflight weather briefing for one or more airports. Guides the LLM to call `aviation_get_metar`, `aviation_get_taf`, and `aviation_get_advisories` in sequence and synthesize a go/no-go picture with flight categories and active hazards.

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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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

Clone the repository:

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

Navigate into the directory:

cd aviation-weather-mcp-server

Install dependencies:

bun install

Configure environment:

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

Configuration

Variable	Description	Default
`AWC_BASE_URL`	Base URL for the NWS AWC Data API.	`https://aviationweather.gov/api/data`
`AWC_TIMEOUT_MS`	Per-request timeout in milliseconds (1000–60000).	`10000`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

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

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/prompts and inits services.
`src/config`	Server-specific env var parsing (`AWC_BASE_URL`, `AWC_TIMEOUT_MS`).
`src/services/aviation-weather`	AWC Data API client — HTTP fetch, retry with exponential backoff, response normalization.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/mcp-server/prompts`	Prompt definitions (`*.prompt.ts`).
`tests/`	Unit and integration tests mirroring `src/`.

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.

Install

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

AWC_BASE_URLdefault https://aviationweather.gov/api/data

Base URL for the AWC Data API. Useful for testing against a mock or staging instance.

AWC_TIMEOUT_MSdefault 10000

Per-request timeout in milliseconds (1000–60000).

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "aviation-weather-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/aviation-weather-mcp-server@0.1.5",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "AWC_BASE_URL": "https://aviationweather.gov/api/data",
        "AWC_TIMEOUT_MS": "10000"
      }
    }
  }
}