Aviation Weather MCP Server
cyanheads/aviation-weather-mcp-server
Dados meteorológicos de aviação em tempo real para MCP
Ver no GitHubServidor MCP que fornece dados de meteorologia aeronáutica em tempo real do NWS Aviation Weather Center. Acessa METARs (observações), TAFs (previsões), PIREPs (relatórios de pilotos) e SIGMETs/AIRMETs (avisos). Suporta integração via STDIO ou HTTP streamável.
Instalação
npx convez-ai cyanheads/aviation-weather-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar condições meteorológicas atuais em aeroportos específicos
- Integrar previsões aeronáuticas em aplicações de planejamento de voo
- Recuperar relatórios de pilotos e avisos meteorológicos ativos
Veredito

MCP server especializado e bem estruturado para aviação. Implementação técnica sólida com suporte a múltiplas formas de acesso, ideal para integrações em sistemas aeronáuticos ou assistentes que precisem de dados meteorológicos precisos em tempo real.
README
A tradução para o português deste README ainda está na fila.
Public Hosted Server: https://aviation-weather.caseyjhand.com/mcp
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).
hoursparameter (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) fromSPECI(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_toin 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 airportbboxfor geographic area search — useful for en-route corridor checksaltitude_min_ft/altitude_max_ftfilters 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_typefilter:sigmet,airmet, orall(default)hazardfilter:CONVECTIVE,TURBULENCE,ICING,IFR,MTN OBSCN,SURFACE WIND,LLWSbboxfilter 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
instructionsfield surfaces the "not an official briefing" safety disclaimer to all clients oninitialize
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
reasonfields andrecoveryhints (e.g., "Verify ICAO IDs withaviation_find_stations") aviation_preflight_briefprompt 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
- 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/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor 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
instructionsfield sent on everyinitialize.
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.