cyanheads/faa-traffic-delays-mcp-server

imageVersion imageLicense imageDocker imageMCP SDK imagenpm imageTypeScript imageBun

imageInstall in Claude Desktop imageInstall in Cursor imageInstall in VS Code

imageFramework

Public Hosted Server: https://faa-traffic-delays.caseyjhand.com/mcp

Overview

Live US air traffic status from the FAA Command Center, the source behind nasstatus.faa.gov. Check airports for ground stops, Ground Delay Programs, delays, and closures; see every active event nationwide; read today's operations plan; and pull the full advisory behind any program, past dates included.

Tools

Agent skill

skills/faa-traffic-delays-guide carries the checks an agent runs before answering with these tools: which flights a program holds, a closure's scope and daily schedule, the age of the operations plan, UTC dates, and finding revised, canceled, or past programs in the advisory index. Plugin hosts load it from the repository, the .mcpb bundle ships it, and the server serves it over MCP as skill://faa-traffic-delays-guide/SKILL.md.

Capability reference

faa_delays_get_airport_status tool

• airports: 1–100 codes, each a 3-character FAA identifier (SEA) or ICAO code (KSEA, PHNL), as an array or comma-separated string. An unknown code fails the whole call as unknown_airport. Only the first 25 distinct airports are processed (cap: 25); processedCount and omittedAirports give the remainder to pass in the next call
• One row per airport, in request order: status (closed, ground_stop, ground_delay_program, delays, restrictions_only, no_active_events), listedInFeed, airportName, artcc, coordinates, and each active event (groundStop, groundDelayProgram with a per-15-minute delayProfile, arrivalDelay / departureDelay, closure and closureNotam with their NOTAM text, deicing). A closure the NOTAM schedules DLY HHMM-HHMM carries dailyWindowUtc and inEffect; outside its window it does not set status to closed
• runwayConfiguration (runways and arrivalRatePerHour) appears only for airports the feed lists. PHX reports timezone: "America/Phoenix" with reportedTimezone: "US/Mountain"
• plannedPrograms: the operations plan's terminal items naming the airport, with the plan's advisory; [] when the plan names it nowhere (not an all-clear), absent when the plan could not 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 are sorted by severity, with reason, delay figures, times, and an advisory reference where the FAA links one; closure rows carry the NOTAM as closureText, plus dailyWindowUtc and inEffect for a daily schedule
• totalActive and countsByType cover the whole feed before the filter. airspace_flow_program rows carry afp detail (constrained area, filters, altitudes, delay profile)
• enRouteFeed (ok, unavailable, format_changed) says whether Airspace Flow Programs were read; if they can't be, they are omitted with a notice unless they were 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)
• Terminal items also carry airports, the FAA identifiers they name (SEA/BFI → SEA, BFI), absent when they name none, such as a metro area or an ARTCC
• announcements lists current ATCSCC announcements (omitted with a notice if unreadable); advisory points to the full plan text for 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 a faa_delays_list_advisories row or an advisory reference. Numbers restart at 1 each UTC day; past advisories stay readable
• Returns title, controlElement, subject, effectiveTime as printed (DDHHMM-DDHHMM) with its effectiveStart and effectiveEnd in ISO 8601 UTC, sentAt in ISO 8601 UTC, and the full text. An unknown number returns found: false with guidance pointing to faa_delays_list_advisories
• Text past 50,000 characters is cut and flagged with truncated and totalChars; failures surface as advisory_service_unavailable or advisory_contract_changed

faa_delays_list_advisories tool

• date (UTC, YYYY-MM-DD; MM/DD/YYYY accepted; no later than tomorrow; default today), optional categories (ground_stop, ground_delay_program, airspace_flow_program, ctop, route, other; aliases gs, gdp, afp), control_element (an airport by FAA or ICAO code, an ARTCC, or DCC for national advisories), limit (default 50; 999 returns any date whole), and offset
• query matches a case-insensitive substring in subject or details, e.g. query: "FCA005" for a named FCA in the plan
• Rows are newest first: number and date (for faa_delays_get_advisory), controlElement, subject, details, and sentAt. totalCount counts every match and nextOffset is present while more remain; no matches returns an empty list with a notice

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 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 data is in the public domain (17 U.S.C. §105)
• Airport codes are checked against a bundled FAA NASR airport directory, with ICAO codes mapped to FAA identifiers (KSEA → SEA), so a mistyped code fails instead of reading as a quiet airport
• Feeds are cached for 60 seconds (the pacing-airport list for 6 hours), and requests to each FAA host are paced
• Parsing is tolerant of the undocumented feed: unreadable rows are skipped and counted in a notice

Agent-friendly output:

• Typed failure reasons separate 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); recovery hints name the next tool to call
• A secondary list that can't be read (pacing airports, the operations plan on airport status, en-route events, announcements) is omitted with a notice instead of failing the call
• fetchedAt dates the snapshot, and a notice flags delays last updated more than 6 hours ago and daily-scheduled closures outside their window
• FAA-authored text is quoted in content[] so it reads as data, and stays verbatim in structuredContent

Limitations:

• Informational, not operational. No substitute for an official preflight briefing or airline operations data.
• Undocumented upstream. nasstatus.faa.gov/api/* is the dashboard's private backend and 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 no_active_events means no FAA program, not on-time flights. Per-flight EDCTs are not in the feed.
• 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

Public Hosted Instance

A public instance is available at https://faa-traffic-delays.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "faa-traffic-delays-mcp-server": {
      "type": "streamable-http",
      "url": "https://faa-traffic-delays.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

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.

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

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.