Aviationstack MCP Server
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., "@Aviationstack MCP Server What's the status of flight AA100 today?"
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.
Aviationstack MCP Server
This project is an MCP (Model Context Protocol) server that provides a set of tools to interact with the AviationStack API. It exposes endpoints for retrieving real-time and future flight data, aircraft and airplane details, and core reference data (airports, airlines, routes, taxes), making it easy to integrate aviation data into your applications.
You can also find the Aviationstack MCP server in these well-known MCP server repositories for easy access:
Demo
https://github.com/user-attachments/assets/9325fcce-8ecc-4b01-8923-4ccb2f6968f4
Features
Look up a single flight by its flight number
Get flights for a specific airline
Fetch historical flights by date
Retrieve arrival and departure schedules for airports
Fetch future flight schedules (from tomorrow through about 12 months ahead)
Get random aircraft types
Get detailed info on random airplanes
Get detailed info on random countries
Get detailed info on random cities
List airports, airlines, routes, and taxes
All endpoints are implemented as MCP tools and are ready to be used in an MCP-compatible environment.
Every tool returns the same JSON envelope. On success: {"ok": true, "count": N, "data": [...]}, plus a pagination block on the list_* tools and a message when there were no matches. On failure: {"ok": false, "context": "...", "error": "..."}. Any limit is capped at 100 records per call.
Prerequisites
Aviationstack API Key (You can get a FREE API Key from Aviationstack)
Python 3.13 or newer
uv package manager installed
Available Tools
Tool | Description | Parameters |
| Look up one flight by its IATA flight number, for today or a given date. | - |
| Get live flights for a specific airline. | - |
| Get historical flights for a date (Basic plan+). | - |
| Get today's arrival or departure board for a given airport and airline. Current day only. | - |
| Get scheduled flights for a given airport, airline, and future date. Covers tomorrow through about 12 months ahead, including the next 7 days. | - |
| Get aircraft types from a random offset in the dataset. | - |
| Get detailed info on airplanes from a random offset in the dataset. | - |
| Get detailed info on countries from a random offset in the dataset. | - |
| Get detailed info on cities from a random offset in the dataset. | - |
| List airports. | - |
| List airlines. | - |
| List routes. | - |
| List aviation taxes. | - |
Prompts
The server ships reusable prompts that steer a model toward the right tool.
Prompt | Arguments | Purpose |
|
| Check one specific flight, and explain its codeshares. |
|
| Query live flights for an airline. |
|
| Query a future airport schedule. |
|
| Explore airport, airline, route or tax reference data. |
Resources
Resource | URI | Contents |
|
| API base URL and the accepted API key variables. |
|
| The Aviationstack endpoints each tool calls. |
|
| A sample payload for a given tool. |
Development
The main server logic is in
src/aviationstack_mcp/server.py.All MCP tools are defined as Python functions decorated with
@mcp.tool().Each tool is a thin wrapper that validates input with a Pydantic model, then calls the matching plain function. Tests target the plain functions.
The server uses the
FastMCPclass frommcp.server.fastmcp. Themcpdependency is pinned to<2, because 2.x renamesFastMCPtoMCPServer.Tools never raise. Every failure is caught and returned as the error envelope.
Set up and run the checks the CI runs:
uv sync --all-groups
# Unit tests
uv run python -m unittest discover -s tests -v
# Lint, must stay at 10.00/10
uv run pylint $(git ls-files '*.py')
# Coverage
uv run coverage run --source=aviationstack_mcp -m unittest discover -s tests
uv run coverage report.well-known/mcp/server-card.json is generated, not hand-edited. After changing any tool,
prompt or resource, regenerate it or CI will fail:
uv run python scripts/generate_server_card.py # rewrite the card
uv run python scripts/generate_server_card.py --check # what CI runsMCP Server configuration
To add this server to your favorite MCP client, you can add the following to your MCP client configuration file.
Using
uvxwithout cloning the repository (recommended)
{
"mcpServers": {
"Aviationstack MCP": {
"command": "uvx",
"args": [
"aviationstack-mcp"
],
"env": {
"AVIATION_STACK_API_KEY": "<your-api-key>"
}
}
}
}By cloning the repository and running the server locally
{
"mcpServers": {
"Aviationstack MCP": {
"command": "uv",
"args": [
"--directory",
"/path/to/aviationstack-mcp/src/aviationstack_mcp",
"run",
"-m",
"aviationstack_mcp",
"mcp",
"run"
],
"env": {
"AVIATION_STACK_API_KEY": "<your-api-key>"
}
}
}
}Related MCP server: AllFlyghts MCP Server
License
This project is licensed under the MIT License. See LICENSE for details.
Available Tools
13 toolsflight_arrival_departure_scheduleA
Return today's arrival or departure board for an airport, optionally filtered by airline name. Returns airline, flight number, scheduled, estimated and actual times, terminals, gates and departure delay per flight. Covers the current day only: for any later date use future_flights_arrival_departure_schedule instead.
Inputs: schedule_type (required), airport_iata_code (required), airline_name, number_of_flights. Returns: result
flights_with_airlineA
Return live flights for one airline, optionally narrowed to a single flight status. Returns flight number, airline, departure and arrival airports with timezones, scheduled departure time, status, delay, terminal and gate. Use this to survey an airline's current activity; use get_flight_status when you already know the flight number.
Inputs: airline_name (required), number_of_flights (required), flight_status. Returns: result
future_flights_arrival_departure_scheduleA
Return the scheduled arrival or departure board for an airport on a specific future date. Covers any date from tomorrow through about 12 months ahead, including the next 7 days. Returns airline, flight number, scheduled times, arrival airport, terminal, gate and aircraft model. Use flight_arrival_departure_schedule for today's board instead.
Inputs: schedule_type (required), airport_iata_code (required), date, airline_iata, +1 more. Returns: result
get_flight_statusA
Look up one specific flight by its IATA flight number, for the current day or a given date. Returns flight status plus scheduled, estimated and actual times, terminal, gate, baggage belt and delay minutes for both ends, with the operating flight ordered ahead of its codeshares. Use this when the question names a flight number; use flights_with_airline to browse an airline's flights, or historical_flights_by_date for past dates.
Inputs: flight_iata (required), flight_date. Returns: result
historical_flights_by_dateA
Return flights that already operated on a past date, with optional airline and route filters. Returns flight date, status, flight number, airline, and both airports with their scheduled times. Requires the Basic plan or higher. Use this for past dates only: use flight_arrival_departure_schedule for today and future_flights_arrival_departure_schedule for later dates.
Inputs: flight_date (required), number_of_flights (required), arr_iata, dep_iata, +1 more. Returns: result
list_airlinesA
List airlines from the reference catalog, one page at a time, with optional text search. Each record has airline name, IATA and ICAO codes, callsign, operational status, country name and ISO2, alongside a pagination block carrying limit, offset and total. Use search to resolve an airline name to the IATA code the flight tools expect.
Inputs: limit, offset, search. Returns: result
list_airportsA
List airports from the reference catalog, one page at a time, with optional text search. Each record has airport name, IATA and ICAO codes, city IATA code, country name and ISO2, timezone and GMT offset, alongside a pagination block carrying limit, offset and total. Use search to resolve an airport name to the IATA code the flight tools expect.
Inputs: limit, offset, search. Returns: result
list_routesA
List scheduled routes, one page at a time, filtered by any combination of airline, departure airport and arrival airport. Each record has airline IATA and ICAO codes, flight number, and departure and arrival airport codes, alongside a pagination block carrying limit, offset and total. This says which routes exist, not whether a flight is operating: use get_flight_status for that. Requires the Basic plan or higher.
Inputs: limit, offset, arr_iata, dep_iata, +1 more. Returns: result
list_taxesA
List aviation taxes from the reference catalog, one page at a time, with optional text search. Each record has tax id, tax name and the associated IATA code, alongside a pagination block carrying limit, offset and total. This is static reference data, not fares or amounts charged on a booking. Requires a paid plan.
Inputs: limit, offset, search. Returns: result
random_aircraft_typeA
Return a random sample of aircraft types from the Aviationstack reference catalog. Each record has aircraft_name and iata_code. Records are drawn from a random offset, so repeated calls return different rows. This samples the catalog and cannot look up a specific model: there is no search parameter.
Inputs: number_of_aircraft (required). Returns: result
random_airplanes_detailed_infoA
Return a random sample of individual airplanes from the reference catalog. Each record has model name and code, series, production line, registration number, owner, age, engine type and count, delivery date and first flight date. Records are drawn from a random offset, so repeated calls return different aircraft. Sampling only: there is no lookup by registration.
Inputs: number_of_airplanes (required). Returns: result
random_cities_detailed_infoA
Return a random sample of cities from the reference catalog. Each record has city name, IATA code, country ISO2, latitude, longitude, timezone, GMT offset and geoname id. Records are drawn from a random offset, so repeated calls return different cities. Sampling only: there is no lookup by city name.
Inputs: number_of_cities (required). Returns: result
random_countries_detailed_infoA
Return a random sample of countries from the reference catalog. Each record has country name, capital, continent, ISO2, ISO3 and numeric ISO codes, FIPS code, currency name and code, phone prefix and population. Records are drawn from a random offset, so repeated calls return different countries. Sampling only: there is no lookup by country name or code.
Inputs: number_of_countries (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each flight tool is scoped by a distinct combination of temporal window and entity: specific flight, airline activity, past-date search, today's airport board, or future airport board. The descriptions explicitly cross-reference alternatives, and the reference tools separately cover airports, airlines, routes, taxes, aircraft types, airplanes, countries, and cities.
All names are snake_case and readable, but the action style is mixed: get_flight_status, flights_with_airline, historical_flights_by_date, flight_arrival_departure_schedule, future_flights_arrival_departure_schedule, random_*, and list_*. The list_* and random_* families are consistent internally, but the flight tools do not follow a single verb_noun convention.
The 13 tools cover flight queries plus several reference catalogs without becoming unwieldy. Each tool maps to a distinct endpoint or use case, and the count sits comfortably in the appropriate range.
Core flight workflows are covered: current flight status, airline activity, historical flights, and today/future airport boards, along with airport, airline, and route lookups. However, aircraft types, individual airplanes, countries, and cities are random-sample only with no targeted lookup or search, leaving notable gaps for specific reference queries.
Maintenance
Related MCP Connectors
Aviationstack MCP — global flight + airport + airline data
Unofficial FlightAware MCP — wraps FlightAware AeroAPI v4 (aeroapi.flightaware.com)
Unofficial FlightStats MCP — wraps the Cirium FlightStats Flex API (api.flightstats.com/flex)
Live flight status and scheduled-route search via the official FlightAware AeroAPI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive flight tracking capabilities using the OpenSky Network API, enabling real-time flight data, geographic searches, historical data, and airport operations through MCP tools.MIT
- FlicenseNot gradedqualityDmaintenanceEnables flight search, location lookup, and city information retrieval using the AllFlyghts public API through MCP tools.-
- AlicenseBqualityDmaintenanceEnables AI assistants to query flight routes, real-time flight tracking, weather, and transfer flights via standardized MCP tools.10MIT
- AlicenseNot gradedqualityBmaintenanceAviationstack MCP server that provides tools to access global flight and aviation data including airports, airlines, cities, countries, and routes.87 npmMIT