Skip to main content
Glama

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

get_flight_status(flight_iata: str, flight_date: str = "")

Look up one flight by its IATA flight number, for today or a given date.

- flight_iata: Flight IATA number (e.g., "AA100") - flight_date: Optional date in YYYY-MM-DD format

flights_with_airline(airline_name: str, number_of_flights: int, flight_status: str = "")

Get live flights for a specific airline.

- airline_name: Name of the airline (e.g., "Delta Air Lines") - number_of_flights: Number of flights to return - flight_status: Optional status filter: scheduled, active, landed, cancelled, incident, diverted

historical_flights_by_date(flight_date: str, number_of_flights: int, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")

Get historical flights for a date (Basic plan+).

- flight_date: Date in YYYY-MM-DD format - number_of_flights: Number of flights to return - airline_iata: Optional airline IATA filter - dep_iata: Optional departure airport IATA filter - arr_iata: Optional arrival airport IATA filter

flight_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_name: str, number_of_flights: int)

Get today's arrival or departure board for a given airport and airline. Current day only.

- airport_iata_code: IATA code of the airport (e.g., "JFK") - schedule_type: "arrival" or "departure" - airline_name: Name of the airline - number_of_flights: Number of flights to return

future_flights_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_iata: str, date: str, number_of_flights: int)

Get scheduled flights for a given airport, airline, and future date. Covers tomorrow through about 12 months ahead, including the next 7 days.

- airport_iata_code : IATA code of the airport - schedule_type: "arrival" or "departure" - airline_iata: IATA code of the airline (e.g., "DL" for Delta) - date: Date in YYYY-MM-DD format, from tomorrow up to about 12 months ahead - number_of_flights: Number of flights to return

random_aircraft_type(number_of_aircraft: int)

Get aircraft types from a random offset in the dataset.

- number_of_aircraft: Number of aircraft types to return

random_airplanes_detailed_info(number_of_airplanes: int)

Get detailed info on airplanes from a random offset in the dataset.

- number_of_airplanes: Number of airplanes to return

random_countries_detailed_info(number_of_countries: int)

Get detailed info on countries from a random offset in the dataset.

- number_of_countries: Number of countries to return

random_cities_detailed_info(number_of_cities: int)

Get detailed info on cities from a random offset in the dataset.

- number_of_cities: Number of cities to return

list_airports(limit: int = 10, offset: int = 0, search: str = "")

List airports.

- limit: Number of results to return - offset: Pagination offset - search: Optional search query

list_airlines(limit: int = 10, offset: int = 0, search: str = "")

List airlines.

- limit: Number of results to return - offset: Pagination offset - search: Optional search query

list_routes(limit: int = 10, offset: int = 0, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")

List routes.

- limit: Number of results to return - offset: Pagination offset - airline_iata: Optional airline IATA filter - dep_iata: Optional departure airport IATA filter - arr_iata: Optional arrival airport IATA filter

list_taxes(limit: int = 10, offset: int = 0, search: str = "")

List aviation taxes.

- limit: Number of results to return - offset: Pagination offset - search: Optional search query

Prompts

The server ships reusable prompts that steer a model toward the right tool.

Prompt

Arguments

Purpose

plan_flight_status_lookup

flight_iata, flight_date

Check one specific flight, and explain its codeshares.

plan_airline_flight_lookup

airline_name, number_of_flights

Query live flights for an airline.

plan_future_schedule_lookup

airport_iata_code, date, schedule_type

Query a future airport schedule.

plan_reference_data_lookup

data_type, search

Explore airport, airline, route or tax reference data.

Resources

Resource

URI

Contents

server_metadata

aviationstack://meta/server

API base URL and the accepted API key variables.

aviationstack_endpoints

aviationstack://meta/endpoints

The Aviationstack endpoints each tool calls.

tool_input_examples

aviationstack://examples/tool-input/{tool_name}

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 FastMCP class from mcp.server.fastmcp. The mcp dependency is pinned to <2, because 2.x renames FastMCP to MCPServer.

  • 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 runs

MCP Server configuration

To add this server to your favorite MCP client, you can add the following to your MCP client configuration file.

  1. Using uvx without cloning the repository (recommended)

{
  "mcpServers": {
    "Aviationstack MCP": {
      "command": "uvx",
      "args": [
        "aviationstack-mcp"
      ],
      "env": {
        "AVIATION_STACK_API_KEY": "<your-api-key>"
      }
    }
  }
}
  1. 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 tools
flight_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

    A4.3/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers