faa-traffic-delays-mcp-server

---

Overview

Real-time air traffic management status from the FAA Air Traffic Control System Command Center (ATCSCC), read from the NAS Status feed behind nasstatus.faa.gov and the ATCSCC advisories database. Check US airports for ground stops, Ground Delay Programs, delays, and closures; list every active event nationwide, en-route Airspace Flow Programs included; and read the operations plan for later in the day and the full advisory behind each program. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
faa_delays_get_airport_status	Current status of 1–25 US airports: ground stop, Ground Delay Program, delays, closures, deicing, and runway configuration with arrival rate
faa_delays_list_active_events	Every active event across the National Airspace System, Airspace Flow Programs included, sorted by severity with per-type counts
faa_delays_get_operations_plan	The Command Center's operations plan: programs and initiatives expected later today, with planned time and likelihood
faa_delays_get_advisory	Full text of one ATCSCC advisory by number and UTC date: program rate, scope, comments, and the plan's constraints
faa_delays_list_reference	Decode event types, traffic-management terms, ARTCC codes, the FAA pacing airports, and identifier formats

Capability reference

faa_delays_get_airport_status _tool

• airports: 1–25 codes, each a 3-character FAA identifier (SEA) or its ICAO code (KSEA, PHNL), case-insensitive, as an array or a comma-separated string; a code not in the bundled FAA NASR directory fails the whole call as unknown_airport (with unknownCodes) before any FAA request
• One row per airport, in request order: status (closed, ground_stop, ground_delay_program, delays, restrictions_only, no_active_events), listedInFeed, the resolved airportName, requestedAs for an ICAO input, and each active event — groundStop, groundDelayProgram with a per-15-minute delayProfile, arrivalDelay / departureDelay bands, closure, closureNotam, deicing
• runwayConfiguration (runways and arrivalRatePerHour) only for airports the feed lists; isPacingAirport and timezone are omitted with a notice when the FAA pacing-airport list can't be read

---

faa_delays_list_active_events _tool

• Optional event_types filter over ground_stop, ground_delay_program, airspace_flow_program, arrival_delay, departure_delay, airport_closure, closure_notam, deicing (aliases gs, gdp, afp); rows sorted by severity, with reason, delay figures, times, and an advisory reference where the FAA links one
• totalActive and countsByType cover the whole feed before the filter, and shown / appliedEventTypes echo what was returned; airspace_flow_program rows carry afp detail (constrained area, departure and arrival filters, altitudes, delay profile)
• enRouteFeed (ok, unavailable, format_changed) reports whether Airspace Flow Programs were read: an en-route failure omits them with a notice instead of failing the call, unless they are the only type requested

---

faa_delays_get_operations_plan _tool

• No input; terminalPlanned and enRoutePlanned items carry text, timeQualifier (after, until, by, between), timeUtc (HHMM with no date), and likelihood (possible, probable, expected)
• announcements lists current ATCSCC announcements ([] when none, absent with a notice when that list can't be read); advisory opens the full plan text with faa_delays_get_advisory

---

faa_delays_get_advisory _tool

• advisory_number (1–999) and date (UTC, YYYY-MM-DD; MM/DD/YYYY accepted), taken from an advisory reference's number and date; numbers restart at 1 each UTC day, and past advisories stay readable
• Returns title, controlElement, subject, effectiveTime, sentAt, and the full text; a number the database doesn't hold returns found: false with guidance rather than an error
• Text past 50,000 characters is cut and reported through truncated and totalChars; page failures surface as advisory_service_unavailable or advisory_contract_changed

---

faa_delays_list_reference _tool

• topic: event_types, terms, artccs, pacing_airports, or identifiers
• Only pacing_airports calls the FAA (live, cached 6 hours); identifiers also reports the bundled NASR airport directory's cycle date and airport count

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

FAA-specific:

• Reads the NAS Status feed (nasstatus.faa.gov/api) and the ATCSCC advisories database (www.fly.faa.gov/adv), keyless; FAA status and NASR airport data are US federal works in the public domain (17 U.S.C. §105), published by the Federal Aviation Administration
• Airport codes are checked against a bundled snapshot of the FAA NASR airport directory, with ICAO codes mapped to FAA identifiers by lookup (KSEA → SEA, PHNL → HNL), so a mistyped code fails instead of reading as a quiet airport
• Each feed is cached in process for 60 seconds (the pacing-airport list for 6 hours) with one shared in-flight request, and requests to each FAA host are paced; an expired snapshot is never served when a refresh fails
• Tolerant parsing of the undocumented feed: an unreadable row is skipped and counted in the notice, and a wrong-typed field is dropped rather than coerced

Agent-friendly output:

• Typed failure reasons: an outage (feed_unavailable), a slow or throttled FAA (retry_deadline_exceeded, upstream_rate_limited, pacer_shed), and a format change (feed_contract_changed, not retryable) stay distinct; each recovery hint names the tool to call next, and rate-limit errors carry retryAfter when it is known
• Graceful partial failure: a secondary FAA list that can't be read (pacing airports, en-route events, announcements) is omitted with a flag or notice instead of failing the call
• Freshness on every feed tool: fetchedAt for the snapshot, updatedAt on each event, and a notice when an arrival or departure delay entry was last updated more than 6 hours earlier, since the FAA feed can keep a delay entry after it lapses
• FAA-authored text (reasons, NOTAMs, comments, announcements, advisory text) is flattened, quoted, or fenced in content[] so it reads as data, and stays verbatim in structuredContent

Limitations:

• Informational, not operational. Not an operational source for flight planning: no substitute for an official preflight briefing or airline operations data.
• Undocumented upstream. nasstatus.faa.gov/api/* is the dashboard's private backend: no schema, terms, versioning, or published limits, and it can change without notice. The server fails with feed_contract_changed rather than guess.
• Airport coverage is event-driven. The feed lists only airports with an active event, so runway configuration and arrival rate are unavailable for airports without one, and no_active_events means no FAA program, not on-time flights. Per-flight EDCTs are not in the feed.
• En-route row shape is inferred, not observed. Airspace Flow Program rows follow the shape the NAS Status dashboard's own code reads; a mismatch degrades the national list with enRouteFeed: "format_changed" rather than failing it.
• The airport directory is a snapshot. An identifier the FAA assigns after the bundled NASR cycle is rejected as unknown until the next refresh. US airports only.

Getting started

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "faa-traffic-delays-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/faa-traffic-delays-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.4.0 or higher (or Node.js v24+).
• No API key or account: the FAA feeds are public.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/faa-traffic-delays-mcp-server.git

2. Navigate into the directory:

cd faa-traffic-delays-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# every variable has a default; edit .env only to change transport, logging, or telemetry

Configuration

The server reads no environment variables of its own: the FAA hosts, cache lifetimes, and request pacing are fixed in the services. These framework variables cover transport, logging, and telemetry.

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_HOST	HTTP server host.	127.0.0.1
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto.	stateless
MCP_AUTH_MODE	Authentication: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	info
LOGS_DIR	Directory for log files (Node.js only).	<app-root>/logs
OTEL_ENABLED	Enable OpenTelemetry.	false

See .env.example for the common framework overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

• Refresh the airport directory from the current FAA NASR cycle (needs network access and the system unzip):

  bun run refresh:airports
  

Project structure

Directory	Purpose
src/mcp-server/tools	Tool definitions (*.tool.ts), plus shared output schemas, notice fragments, and Markdown helpers for FAA-authored text.
src/services/nas-status	NAS Status feed client and tolerant feed parsers.
src/services/advisory	ATCSCC advisories database client, page parser, and advisory URL builder.
src/services/airport-directory	Bundled FAA NASR airport directory and ICAO → FAA crosswalk (generated module).
src/services/upstream	Shared FAA fetch boundary (pacing, retry, status classification) and the in-process cache.
scripts/refresh-airport-directory.ts	Regenerates the airport directory module (bun run refresh:airports).
tests/	Unit and integration tests, mirroring the src/ structure, with synthetic FAA fixtures.
docs/design.md	Tool surface design, upstream API notes, design decisions, and known limitations.

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 logging; FAA feeds are cached in process, not in ctx.state
• Register new tools in allToolDefinitions in src/mcp-server/tools/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.