# flightaware-mcp [Health: Active]

**Category:** 🚀 Aerospace & Astrodynamics  
**Repository:** https://github.com/chrischall/flightaware-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1984  
**Views:** 3  
**Installs:** 3  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/flightaware-mcp

## Description
Live flight tracking and aviation data via FlightAware AeroAPI (flights, airports, alerts).

## Tools
Capabilities this server exposes over MCP:

- **fa_get_flights** — Get flights for an ident — a flight designator (e.g. UAL123, AAL100), aircraft registration (e.g. N12345), or fa_flight_id. Returns recent, current, and scheduled flights for that ident.
- **fa_search_flights** — Search airborne flights using AeroAPI's simplified query syntax — a single string of "-key value" pairs. Keys: -prefix -type -idents -identOrReg -airline -destination -origin -originOrDestination -aboveAltitude -belowAltitude -aboveGroundspeed -belowGroundspeed -latlong "MINLAT MINLON MAXLAT MAXLON" -filter {ga|airline}. Example: -airline UAL -belowAltitude 30000
- **fa_search_flights_advanced** — Search flights using AeroAPI's full structured query language (more expressive than fa_search_flights). The `query` is a space-separated list of {operator key value} predicates, e.g. "{match ident UAL*} {> alt 300} {= dest KLAX}". Operators: true/false/null/notnull/=/!=/</>/<=/>=, match/notmatch (case-insensitive wildcards), range (two values), in/orig_or_dest/aircraftType/ident/ident_or_reg ({a b c} value lists), airline (1=airline, 0=GA). Common keys: ident, orig, dest (ICAO codes), aircraftType, alt (hundreds of ft), prefix, lifeguard, cancelled, arrived.
- **fa_get_flight_track** — Get the position track (breadcrumb log) for a specific flight by fa_flight_id.
- **fa_get_flight_position** — Get the most recent reported position for an in-air flight by fa_flight_id.
- **fa_get_flight_route** — Get the decoded route (fixes/waypoints) for a specific flight by fa_flight_id.
- **fa_get_flight_map** — Get a rendered map image (PNG) of a flight by fa_flight_id. Writes the PNG to disk (default: $AEROAPI_OUTPUT_DIR, else ~/Downloads/flightaware-mcp) and returns the path, or returns it inline as base64 when inline:true.
- **fa_get_flight_history** — Get historical flights for an ident (designator, registration, or fa_flight_id) beyond the recent window covered by fa_get_flights. NOTE: historical data requires a Standard or Premium AeroAPI tier — the free Personal tier returns 401.
- **fa_search_flight_positions** — Search live flight POSITIONS using the structured "{operator key value}" query language (same grammar as fa_search_flights_advanced — NOT the simplified "-key value" syntax). Returns position points rather than flight summaries. Example: {match ident UAL*} {> alt 300}.
- **fa_count_flights** — Count flights matching a query without returning the flights themselves. Returns { count }. Uses the SIMPLIFIED "-key value" syntax (same as fa_search_flights, NOT the structured grammar of fa_search_flights_advanced). Example: -airline UAL -belowAltitude 30000.
- **fa_resolve_flight** — Resolve a flight ident (designator/registration) to its canonical form and any alternate idents. NOTE: requires a Standard or Premium AeroAPI tier — the free Personal tier returns 401.
- **fa_get_airport** — Get details for an airport by code (ICAO like KJFK, IATA like JFK, or LID).
- **fa_get_airport_flights** — Get a flight board for an airport: all flights, or just arrivals/departures/scheduled_arrivals/scheduled_departures.
- **fa_list_airports** — List airports known to AeroAPI (paged). Use the cursor to page through.
- **fa_get_nearby_airports** — Find airports near a latitude/longitude within a radius (statute miles).
- **fa_get_airport_delays** — Get current airport delays — all delayed airports, or just one when `id` is given.
- **fa_get_airport_weather** — Get weather for an airport: current METAR observations, or the TAF forecast.
- **fa_get_airport_flight_counts** — Get current flight counts at an airport: { departed, enroute, scheduled_arrivals, scheduled_departures }.
- **fa_get_airport_routes** — Get the most popular routes (with aircraft types, counts, and filed altitudes) flown between an origin and destination airport.
- **fa_resolve_airport** — Resolve an airport code to its canonical AeroAPI identifier (and equivalents). NOTE: requires a Standard or Premium AeroAPI tier — the free Personal tier returns 401.
- **fa_get_operator** — Get details for an operator (airline) by code (ICAO like UAL, or IATA like UA).
- **fa_get_operator_flights** — Get a flight board for an operator (airline): all flights, or arrivals/departures/enroute/scheduled.
- **fa_list_operators** — List operators (airlines) known to AeroAPI (paged). Use the cursor to page through.
- **fa_healthcheck** — Resolves the credential the way real tools do, then makes one authenticated request to aeroapi.flightaware.com. Reports which source supplied the credential, whether aeroapi.flightaware.com accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a aeroapi.flightaware.com-side problem'. Read-only; never returns the credential itself. Call this when a real tool fails and you want to know which hop broke.
- **fa_get_aircraft_owner** — Get the registered owner of an aircraft by tail number / registration (e.g. N12345).
- **fa_get_scheduled_flights** — Get airline-scheduled flights between two dates (YYYY-MM-DD), optionally filtered by origin, destination, airline, or flight number.
- **fa_foresight_search** — Predictive flight search via AeroAPI Foresight (Boolean query language, like fa_search_flights_advanced, but predicted data). NOTE: Foresight is a premium tier — expect a 402/403 unless your subscription includes it.
- **fa_list_alerts** — List the flight alerts configured on your AeroAPI account. Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_get_alert** — Get a single configured flight alert by its id. Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_create_alert** — Create a flight alert on your AeroAPI account. Asks the user to confirm first: a confirmation prompt where the client supports one (unless the server sets MCP_CONFIRM_ELICITATION=off); otherwise the first call returns a preview of the request (method, path, body) and a confirmToken, makes NO network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_update_alert** — Update an existing flight alert (replaces its configuration). Asks the user to confirm first: a confirmation prompt where the client supports one (unless the server sets MCP_CONFIRM_ELICITATION=off); otherwise the first call returns a preview of the request (method, path, body) and a confirmToken, makes NO network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_delete_alert** — Delete a flight alert by id. Asks the user to confirm first: a confirmation prompt where the client supports one (unless the server sets MCP_CONFIRM_ELICITATION=off); otherwise the first call returns a preview of the request (method, path, body) and a confirmToken, makes NO network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_get_alerts_endpoint** — Get the current delivery (webhook) endpoint configured for your AeroAPI alerts. Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).
- **fa_set_alerts_endpoint** — Set the delivery (webhook) endpoint AeroAPI POSTs alert notifications to. Asks the user to confirm first: a confirmation prompt where the client supports one (unless the server sets MCP_CONFIRM_ELICITATION=off); otherwise the first call returns a preview of the request (method, path, body) and a confirmToken, makes NO network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Requires a Standard or Premium AeroAPI tier (the free Personal tier returns 401).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "flightaware-mcp": {
    "command": "npx",
    "args": ["-y","@chrischall/flightaware-mcp"]
  }
}
```

## Documentation & README

# flightaware-mcp

[![npm](https://img.shields.io/npm/v/@chrischall/flightaware-mcp)](https://www.npmjs.com/package/@chrischall/flightaware-mcp)

MCP server for **FlightAware AeroAPI** (v4) — live flight tracking and aviation data for Claude. Track flights, read airport boards, look up operators and aircraft, fetch scheduled flights, and manage flight alerts, all over stdio.

> Developed and maintained by AI (Claude Code). Use at your own discretion.

## Quick start

```json
{
  "mcpServers": {
    "flightaware": {
      "command": "npx",
      "args": ["-y", "@chrischall/flightaware-mcp"],
      "env": { "AEROAPI_API_KEY": "your-aeroapi-key-here" }
    }
  }
}
```

Get a key at [flightaware.com/aeroapi/portal](https://www.flightaware.com/aeroapi/portal/). The free **Personal** tier (500 calls/month) is enough to start; AeroAPI bills per query.

## Tools

| Area | Tools |
| --- | --- |
| Flights | `fa_get_flights`, `fa_search_flights`, `fa_search_flights_advanced`, `fa_search_flight_positions`, `fa_count_flights`, `fa_get_flight_track`, `fa_get_flight_position`, `fa_get_flight_route`, `fa_get_flight_map`, `fa_get_flight_history`, `fa_resolve_flight` |
| Airports | `fa_get_airport`, `fa_get_airport_flights`, `fa_get_airport_flight_counts`, `fa_get_airport_routes`, `fa_list_airports`, `fa_get_nearby_airports`, `fa_get_airport_delays`, `fa_get_airport_weather`, `fa_resolve_airport` |
| Operators / aircraft | `fa_get_operator`, `fa_get_operator_flights`, `fa_list_operators`, `fa_get_aircraft_owner` |
| Schedules / predictive | `fa_get_scheduled_flights`, `fa_foresight_search` (premium tier) |
| Alerts | `fa_list_alerts`, `fa_get_alert`, `fa_create_alert`, `fa_update_alert`, `fa_delete_alert`, `fa_get_alerts_endpoint`, `fa_set_alerts_endpoint` |
| Health | `fa_healthcheck` — is this connector working? Reports whether AEROAPI_API_KEY resolved, whether AeroAPI accepted it, and what to fix. Uses a static-cached lookup, so repeat checks are not re-billed. |

Alert mutations (`fa_create_alert`, `fa_update_alert`, `fa_delete_alert`, `fa_set_alerts_endpoint`) ask you to confirm before they write — see [Confirmations](#confirmations).

## Confirmations

Every alert mutation asks for your confirmation before it touches your AeroAPI account. A client that can show a confirmation prompt (Claude Code) shows one. On a client that cannot (claude.ai, Claude Desktop), the first call makes **no** network call and returns a preview of the exact request (method, path, body) plus a `confirmToken`; only a repeat call with that token sends it. A token acts once, expires, and is refused if the request changed since the preview.

| variable | default | |
|---|---|---|
| `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt, unless `MCP_CONFIRM_ELICITATION=off`. An unrecognised value is treated as `refuse`. |
| `MCP_CONFIRM_ELICITATION` | `on` | `off` never sends a confirmation prompt, so every client gets the `MCP_CONFIRM_MODE` path. Set it for a client that declares it can show prompts but never does (the gated call hangs — opencode 2.0.x). Any other value stays `on`, with a stderr warning. |
| `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |

## Configuration

| Var | Required | Purpose |
| --- | --- | --- |
| `AEROAPI_API_KEY` | yes | Your AeroAPI key (sent as the `x-apikey` header). |
| `AEROAPI_OUTPUT_DIR` | no | Default directory for flight-map PNGs (default: `~/Downloads/flightaware-mcp`). A per-call `output_dir` must be inside this directory (or inside `~/Downloads/flightaware-mcp` when it is unset). |
| `AEROAPI_CACHE_TTL` | no | Seconds to cache identical **live-data** GET responses (default: 15; `0` disables). Cuts AeroAPI per-query billing. |
| `AEROAPI_STATIC_CACHE_TTL` | no | Longer TTL for **reference data** — airport/operator info, routes, ownership, canonical lookups (default: 3600; `0` disables). |

## Development

```bash
npm install
npm run build
npm test
```

Every request rides your own AeroAPI key and counts against your subscription quota. See `docs/FLIGHTAWARE-API.md` for the pinned endpoint surface.

## License

MIT