Purpose
aviationstack-mcp is an MCP (Model Context Protocol) server used to connect aviation data from the AviationStack API to MCP-compatible clients or applications. It wraps queries for flights, airports, airlines, routes, and more into a set of MCP tools, making them easy to call in MCP-compatible environments.
Main Capabilities
The tools provided by the project can perform the following queries:
- Query a single flight by flight number
- Retrieve flights for an airline
- Retrieve historical flights by date
- Retrieve arrival and departure schedules for an airport
- Retrieve future flight schedules (from tomorrow up to about 12 months)
- Retrieve a random aircraft type
- Retrieve detailed information about a random aircraft
- Retrieve detailed information about a random country
- Retrieve detailed information about a random city
- List airports, airlines, routes, and taxes
All endpoints are implemented as MCP tools and can be used in MCP-compatible environments. In addition, the server also includes reusable prompts to guide the model in selecting the appropriate tools.
Usage
Running the project requires: an AviationStack API Key (a free key can be obtained from AviationStack), Python 3.13 or higher, and the uv package manager installed.
The project's main server logic is located 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 first validates input using Pydantic models, then calls the corresponding plain function, and tests target these plain functions. The server uses the FastMCP class from mcp.server.fastmcp, and the mcp dependency is pinned to <2 because version 2.x renamed FastMCP to MCPServer. Tools do not raise exceptions; all failures are caught and returned in an error envelope.
To connect to an MCP client, add this server to the client's MCP configuration file. The recommended approach is to use uvx without cloning the repository; you can also clone the repository and run the server locally.
.well-known/mcp/server-card.json is a generated file rather than manually edited; after changing any tool, prompt, or resource, it needs to be regenerated, otherwise CI will fail.
Return Format and Limits
Each tool returns a unified JSON envelope. On success, it is {"ok": true, "count": N, "data": [...]}; list-type tools (list_*) additionally include a pagination block, and when there are no matching results, a hint message is included. On failure, it is {"ok": false, "context": "...", "error": "..."}. The maximum number of records per call is 100.
Use Cases
Suitable for scenarios that need to integrate real-time flights, airport schedules, future flight arrangements, and aviation reference data into applications or AI workflows, and can also be used to trigger flight-related queries through natural language or prompts in MCP-compatible environments.
License
The project uses the MIT License; see the LICENSE file for details.
Information Not Yet Provided
Specific details about pricing plans, the specific coverage and update frequency of each type of data, and other limitations beyond deployment environment requirements are not yet provided in the materials.
