flightops-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flightops-mcp why is SFO backed up right now? check weather, traffic, and arrivals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flightops-mcp
A governed Model Context Protocol server that lets an AI agent ask questions about the operational state of an airport — and refuses to answer badly.
Most MCP examples on GitHub are a stdio server with two read-only tools. This one is built around the
parts that actually break in production: OAuth2 client-credential token lifecycles, a credit-metered
upstream with a real 429 contract, honest reporting of missing data, and logs that never contain a
credential or a passenger identifier.
Protocol: MCP revision
2026-07-28(stateless: noinitializehandshake, no session id, per-request capability negotiation), via the Python SDK'sMCPServer.Verified:
73 passed, 0 skipped·ruffclean ·mypy --strictclean · a live end-to-end stdio run against AviationWeather.gov returning real METARs.Cost: zero. Every upstream is free; the authenticated one is optional.
Requirements → what is actually in the repo
Capability | Where it lives | How it is proven |
MCP tools with typed schemas |
|
|
OAuth2 client credentials (M2M) |
|
|
Token lifecycle (expiry, revocation) |
| refresh-ahead inside the skew; a |
Rate limits |
|
|
API budget / least privilege |
|
|
REST integration, no-auth path |
| live NOAA call in CI (advisory job) |
Safe logging, no PII |
| canary tests: a planted token and passenger record must not appear in emitted logs |
Ground-truth reference data |
| distance validated two independent ways |
Failures the model can act on |
| every failure carries |
Containerisation |
| CI builds the image, asserts non-root, asserts the reference DB is baked in |
Version control hygiene |
| no secrets, no multi-megabyte data blobs, LF-normalised |
Related MCP server: AirLabs MCP Server
Architecture
MCP host (Claude Desktop, Inspector, an agent loop)
│ JSON-RPC over stdio or Streamable HTTP
▼
┌───────────────────┐
│ flightops-mcp │ 6 typed tools, guarded
│ (MCPServer) │ failures become data, never 500s
└─────┬───────┬─────┘
OAuth2 M2M │ │ no auth
client_credentials│ │
┌─────▼─────┐ ┌─▼──────────────────┐ ┌──────────────────────┐
│ OpenSky │ │ AviationWeather.gov│ │ OurAirports SQLite │
│ REST API │ │ (NOAA) │ │ (bundled, offline) │
│ credits │ │ METAR / TAF │ │ 49,353 airports │
│ 429 wall │ │ 204 = no data │ │ public domain │
└───────────┘ └────────────────────┘ └──────────────────────┘Three upstreams with three different auth models is the point: the tool layer must not care, and the governance layer must hold for all of them.
Quickstart
uv sync
# The image and CI bake this from the bundled seed; locally it is one command.
uv run python scripts/build_airports_db.py --csv data/airports_seed.csv
# No credentials needed for this much:
uv run flightops-mcp # stdio, for Claude Desktop / mcp devTo unlock the traffic and movement tools, create a free account at
https://opensky-network.org (Account → API Client) and put the pair in .env:
FLIGHTOPS_OPENSKY_CLIENT_ID=your-id-api-client
FLIGHTOPS_OPENSKY_CLIENT_SECRET=your-secretThen in claude_desktop_config.json:
{
"mcpServers": {
"flightops": {
"command": "uv",
"args": ["run", "--project", "/absolute/path/to/flightops-mcp", "flightops-mcp"]
}
}
}The tools
Tool | Upstream | Credentials | Cost |
| OurAirports (local) | none | free, offline |
| AviationWeather.gov | none | free |
| OpenSky | OAuth2 | 1–4 credits |
| OpenSky | OAuth2 | 4 credits per direction |
| all three, composed | OAuth2 for the traffic half | ~9 credits |
| process state | none | free |
Design decisions worth defending
A
429is a contract, not noise. If the upstream says "retry in 3 s" and our ceiling is 5 s, the client waits and retries exactly once. If it says "retry in 900 s", the call returns a structured error carrying that number. Sleeping fifteen minutes inside a tool call is not resilience; it is a hung agent.Tokens are single-flight. Fifty concurrent tool calls that find an empty cache produce one token request, not fifty. The lock is double-checked so the winner refreshes and the rest reuse.
Credits are charged before the request. A call that times out still spends upstream budget, so the local ledger must record it too or the guard under-reports real spend.
/states/allcosts a documented function of bounding-box area —BBox.credit_costmirrors that table and the test pins every band boundary.Absence of data is never "all clear". A
204from NOAA, an empty movements list, and a missing credential produce three different explicitunknownsentries. An empty result from an ADS-B feed means "nothing heard", which is not "nothing happening".Redaction is tested, not asserted. A canary string is planted as a token, a PNR and a passenger name; the emitted log lines are parsed and searched for it. GDPR claims that are not executed are marketing.
Triage degrades to
unknown, not tolow. Without credentials the composite tool still returns weather, and reports severityunknownwith the reason — it does not imply the airport is fine because it could not see the traffic.Provenance travels with the data. Every payload names the upstream and its licence, so an operator can see that "traffic" means ADS-B estimates and "weather" means a government observation.
What running it actually found
Two defects that reviewing the code would not have caught, both now pinned by tests:
NOAA rejects
hourson/taf.GET /api/data/taf?ids=ESGG&format=json&hours=12returnsHTTP 400 {"status":"error","error":"Unexpected query parameter provided"}, while/metaraccepts it happily. The first live run failed here;test_taf_request_omits_the_hours_parameteris the regression.A monotonic clock is the wrong clock for epoch maths. The runtime originally defaulted to
time.monotonic(), which is right for token TTLs and wrong for movement windows — it would have asked OpenSky for traffic in January 1970. Wall clock is now the default, with the reasoning in a comment.
Live data also carries "visib": "6+" — a string, not a number — so a strict isinstance check would
have silently dropped real observations and lost a flag. _number() coerces it, and a test covers it.
The test suite
tests/test_token.py 7 caching, single flight, skew, rejection, malformed response
tests/test_http.py 12 Retry-After (seconds + HTTP-date), retry counts, 429 passthrough
tests/test_opensky.py 21 credit table, decoding, 429 policy, 401 recovery, budget guard
tests/test_airports.py 9 build, resolve, nearest, cross-checked distances
tests/test_weather.py 8 no-data semantics, field mapping, flag thresholds
tests/test_server_tools.py 11 end-to-end through a real MCP client, in memory
tests/test_redaction.py 5 keyed secrets, nested structures, bearer scrubbing, canary
--
73No network, no sleeps, no real clock: transports, sleep and clock are injected. The suite runs on a bare interpreter in under 10 seconds, and CI fails if any test reports as skipped.
What this deliberately does not do
No write operations. Nothing here rebooks a passenger. The scope is observation and triage; a write path needs an idempotency story and a human-approval gate that this repo does not claim.
No LLM in the loop. The server is the hard part and it stays testable without a model. Adding an agent loop on top is the next increment, not a hidden requirement.
No Kubernetes, no frontend, no vector database. Each would be a week of work that demonstrates nothing about integration engineering.
ADS-B is not a schedule. OpenSky deduces arrivals and departures from transponder positions, so origin and destination fields are estimates. That caveat is in the tool description, not only here.
Data sources and licences
Source | Data | Licence / terms |
state vectors, movements | Free for personal and non-profit use; commercial use requires OpenSky's consent | |
AviationWeather.gov (NOAA) | METAR, TAF | US Government open data, public domain |
airports, runways, navaids | Public domain |
This project is the personal-use case: no commercial deployment, no redistribution of upstream data.
Roadmap
v0.1.0 ships the governed tool layer and its test suite. ROADMAP.md is the phased plan
to v1.0: auth-hardened remote server with OBO, observability and a runbook, an agent loop with a human
approval gate, an evaluation harness, then hardening and documentation.
Roadmap → next milestones
Near-term milestones
Streamable HTTP server with MCP-spec OAuth 2.1 resource-server behaviour (JWKS validation, scope challenges in
WWW-Authenticate, no token passthrough)On-behalf-of token exchange (RFC 8693) so a user's identity, not a service's, reaches the upstream
OpenTelemetry traces with
traceparentpropagated into_metaas the 2026-07-28 revision specifiesAn agent loop with a human-approval gate for the first write tool
Tool-calling eval harness: golden scenarios scored for tool choice, argument validity and refusal
Available Tools
6 toolsairport_live_trafficA
Return aircraft currently within a radius of an airport.
Costs 1 OpenSky credit for a box up to 25 square degrees, up to 4 for a very
large radius. Aircraft are sorted by most recently heard.
Args:
airport: ICAO code, e.g. ESGG.
radius_nm: Search radius in nautical miles (5-200).
max_aircraft: Cap on returned aircraft (1-200).
Inputs: airport (required), radius_nm, max_aircraft. Returns: object
airport_movementsA
List estimated arrivals and/or departures for an airport.
Each direction costs 4 OpenSky credits for a live window of under 24 hours.
OpenSky derives these movements from ADS-B, so they are estimates: the
origin/destination fields are inferred from the first and last seen position.
Args:
airport: ICAO code, e.g. ESGG.
direction: "arrival", "departure", or "both".
window_minutes: Look-back window in minutes (5-60; OpenSky serves at most
one hour of history).
Inputs: airport (required), direction, window_minutes. Returns: object
airport_weatherA
Return the latest METAR and TAF for an airport, plus impact flags.
Needs no credentials and spends no OpenSky credits.
Args:
airport: ICAO code, e.g. ESGG.
Inputs: airport (required). Returns: object
disruption_triageA
Assess whether an airport is currently disrupted: weather, traffic, movements.
This is the composite tool an agent should reach for first. It makes one
weather call (free), one movements call per direction and one traffic call
(OpenSky credits), then reports severity together with its reasons and its
unknowns. Severity is advisory only.
Args:
airport: ICAO code, e.g. ESGG.
radius_nm: Traffic search radius in nautical miles (5-200).
Inputs: airport (required), radius_nm. Returns: object
resolve_airportA
Resolve an airport from an ICAO/IATA code or a name fragment.
Offline and free: reads the bundled OurAirports reference database, so it
costs no API credits and works with no credentials configured.
Args:
query: ICAO (ESGG), IATA (GOT), or part of an airport name.
limit: Maximum matches to return (1-20).
Inputs: query (required), limit. Returns: object
upstream_statusA
Report upstream health, credit spend and credential state.
Use before blaming the data: it separates "no credentials", "rate limited"
and "quiet airspace".
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a fairly distinct concern (weather, live traffic, movements, health, airport lookup), and descriptions explicitly separate free vs credit-spending calls. The main overlap is disruption_triage, which internally duplicates weather/traffic/movements, so an agent must judge whether to call the composite or the primitives — the description guides this but does not eliminate the choice. airport_live_traffic vs airport_movements is also a subtle distinction (aircraft currently present vs inferred arrivals/departures) that takes careful reading.
All names are snake_case and readable, but the pattern is mixed: three tools use an 'airport_' prefix while disruption_triage, upstream_status, and resolve_airport do not. Verb style is also inconsistent — resolve_airport is verb_noun while the rest are noun-first (noun_noun or adjective_noun), so there is no predictable verb_noun convention to rely on.
Six tools is well within a tight, purposeful scope for an airport-centric flight ops server. Every tool has a clear job: reference lookup, weather, traffic, movements, composite triage, and diagnostics — no filler or near-duplicates that could be consolidated without losing function.
The read-only airport situational-awareness domain is well covered: weather, live traffic, movements, composite severity, identifier resolution, and upstream/credential diagnostics with an explicit escape hatch for failures. Minor gaps remain — no aircraft/callsign-level lookup, no historical or delay-statistics access beyond the one-hour movements window, and no way to pull deeper airport metadata from resolve_airport.
Maintenance
Related MCP Connectors
Flight and sky conditions for agents, from METAR/TAF and airports to aurora and satellite passes.
Aircraft intelligence for AI agents: valuations with uncertainty bands, FAA registry lookups, cost of ownership, comparable aircraft, fleet search, airworthiness directives and STCs, market metrics and forecasts, verified value reports, pre-buy diligence checklists, logbook search and a watchlist. 38 tools; free tier with OAuth or a Windsock API key.
Read-only airport delay, weather, and 24h forecast tools for AI assistants. Airport-level only.
Airport METAR/TAF weather and FAA delays by airport code. $0.003/call via x402.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegration platform for aviation data sources including weather, NOTAMs, airport information, and flight planning APIs, enabling comprehensive pre-flight preparation and in-flight decision support.146 npm10MIT

AirLabs MCP Serverofficial
AlicenseAqualityDmaintenanceProvides AI assistants with access to real-time flight data, airport schedules, delays, and aviation reference databases through natural language queries.12191 npmMIT- AlicenseAqualityDmaintenanceProvides aviation weather data (METAR, TAF, station search) with a unique assess_conditions tool that returns flight category, confidence, and an escalation gate to indicate when human review is needed.446 npmMIT

FlightQueueofficial
AlicenseNot gradedqualityCmaintenanceProvides AI assistants with real-time and forecast airport intelligence, including security wait times, FAA delays, EU border queues, lounge and terminal info, aviation weather, and baggage performance for over 8,000 airports.MIT