aviationstack

The Aviationstack MCP Server exposes a collection of Python-based MCP tools that wrap the AviationStack API. Each tool is implemented as an MCP function and can be invoked through an MCP-compatible client. The provided tools let you fetch real-time flight data, historical flights by date, upcoming and past arrival/departure schedules for specific airports, random aircraft or airplane details, and detailed reference data such as countries, cities, airports, airlines, routes, and taxes. This makes it straightforward to integrate aviation data into apps, dashboards, or services that rely on structured, MCP-friendly endpoints.

To use the server, start it with the configured MCP client (UVX in the recommended setup). Once the server is running, you can call functions like flights_with_airline, historical_flights_by_date, flight_arrival_departure_schedule, future_flights_arrival_departure_schedule, random_aircraft_type, random_airplanes_detailed_info, random_countries_detailed_info, random_cities_detailed_info, and the list endpoints for airports, airlines, routes, and taxes. Each function accepts clearly defined parameters (e.g., airline names, IATA codes, date strings) and returns results that can be consumed directly by your application.

The API key for AviationStack is required and must be supplied via the AVIATION_STACK_API_KEY environment variable (or configured in your MCP client as shown in the configuration example). This server acts as a convenient, MCP-native facade over AviationStack data, enabling you to compose data workflows and integrate live or historical aviation data with minimal boilerplate.

Prerequisites

• Python 3.13 or newer
• uvx (the MCP/UV execution environment) installed
• AviationStack API key

Installation steps

1. Prepare your environment

• Ensure Python 3.13+ is installed on your system.
• Install uvx if you haven't already (follow the uvx installation instructions for your platform).

2. Obtain the MCP server files

• Clone or download the aviationstack MCP repository to a local directory, or rely on uvx to run the server from its package if available.

3. Configure environment variables

• Acquire an AviationStack API key from https://aviationstack.com/signup/free
• Set AVIATION_STACK_API_KEY in your environment or provide it in your MCP client configuration as shown in the README example:

export AVIATION_STACK_API_KEY="<your-api-key>"

4. Run the server (preferred method: using uvx with the packaged MCP)

• If you are using the recommended uvx approach, you can start the MCP server with:

uvx aviationstack-mcp

5. Verify accessibility

• Ensure the server responds to MCP tool invocations and that the API key is being used for AviationStack requests.

Notes

• If you clone and run locally, ensure you point to the correct module path and run the MCP using the provided mcp run command.
• If you need to run without cloning, use the uvx approach with the packaged module name as shown in the configuration examples.

Tips and common issues:

• Ensure AVIATION_STACK_API_KEY is valid and has not expired; a missing or invalid key will cause API calls to fail.
• When testing, start with simple calls (e.g., list_airports or random_countries_detailed_info) to verify connectivity before invoking more complex endpoints.
• If you encounter rate limits from AviationStack, consider caching results or staggering requests in your application.
• The MCP tools expect correctly formatted parameters; refer to the function signatures in the README to construct valid requests (e.g., date formats like YYYY-MM-DD, or IATA codes).
• If you upgrade the server or API version, verify whether endpoints or parameter names have changed and adjust your MCP client usage accordingly.