Aviationstack MCP Server

An MCP server that gives AI assistants structured access to flight, airport, airline, aircraft, route, tax, and other aviation reference data from the Aviationstack API.

Features

• Search current and historical flight records.
• Search airports and airlines.
• Retrieve airport arrival and departure schedules.
• Browse aircraft types, airplanes, countries, and cities.
• Search routes and aviation taxes.
• Expose planning prompts and machine-readable MCP resources.
• Validate query input with typed Pydantic models.
• Return safe MCP-facing errors without leaking internal details.

Requirements

• Python 3.13 or newer for local development.
• An Aviationstack API key for live requests.
• An MCP-compatible client, such as Claude Desktop, Cursor, or another MCP host.

Installation

Run directly with uvx:

uvx aviationstack-mcp-server

Set your Aviationstack API key in the environment:

export AVIATIONSTACK_API_KEY="your-api-key"

The server reads the key when it starts. It does not require a local checkout or a manually managed virtual environment for normal MCP client use.

Configuration

The required setting is:

Optional settings include:

For local development, create a .env file in the repository root. Do not commit it:

AVIATIONSTACK_API_KEY=your-api-key

MCP Client Configuration

Add the server to an MCP client using the uvx command:

{
  "mcpServers": {
    "aviationstack": {
      "command": "uvx",
      "args": [
        "aviationstack-mcp-server"
      ],
      "env": {
        "AVIATIONSTACK_API_KEY": "your-api-key"
      }
    }
  }
}

The exact location of this configuration depends on the MCP client. Keep the API key in the client's environment configuration rather than putting it in tool arguments or prompts.

Available Tools

Every tool accepts a structured query object. Unless noted otherwise, limit defaults to 10 and must be between 1 and 100. IATA codes are normalized to uppercase by the server.

Examples of structured tool arguments:

{
  "query": {
    "departure_iata": "DEL",
    "arrival_iata": "DXB",
    "limit": 10
  }
}

{
  "query": {
    "airport_iata": "LHR",
    "schedule_type": "departure",
    "limit": 20
  }
}

Available Prompts

Available Resources

Development

Clone the repository and install the development environment with uv:

git clone https://github.com/raviagrawal121/aviationstack-mcp-server.git
cd aviationstack-mcp-server
uv sync
source .venv/bin/activate

Run the server locally after setting AVIATIONSTACK_API_KEY:

uv run aviationstack-mcp-server

Build the source distribution and wheel:

uv build

Testing

The default test suite is offline. MCP integration tests inject an in-memory Aviationstack client, so they do not require an API key or network access:

uv run pytest -m "not live_api and not capability_discovery"

To run only the MCP integration tests:

uv run pytest tests/integration/mcp

Lint the project with Ruff:

uv run ruff check .

Live API Testing

Live tests make real requests and require an Aviationstack API key:

export AVIATIONSTACK_API_KEY="your-api-key"
uv run pytest -m live_api

Capability discovery is opt-in and probes supported endpoint access for the configured account. It makes bounded requests against the live API:

AVIATIONSTACK_LIVE=1 uv run pytest -m capability_discovery -s

Run live tests only when network access and API quota are available. The results depend on the Aviationstack plan associated with the configured key.

Architecture

The server is organized into a small set of layers:

MCP client
    |
MCP tools, prompts, and resources
    |
Application context and domain services
    |
Aviationstack API client and HTTP transport
    |
Aviationstack REST API

• src/aviationstack_mcp_server/mcp/ registers the MCP surface and manages the application lifespan.
• src/aviationstack_mcp_server/services/ contains domain operations for flights, airports, airlines, aircraft, and reference data.
• src/aviationstack_mcp_server/client/ contains the API client, HTTP transport, retries, and client factory.
• src/aviationstack_mcp_server/models/ contains typed response and query models.
• Non-live MCP tests inject a fake client through create_server(client_factory=...); production uses the default factory, which loads Settings and the API key.

Contributing

1. Create a focused branch for your change.
2. Add or update tests for behavior changes.
3. Run the offline test suite and Ruff locally.
4. Update the README when the public MCP surface changes.
5. Open a pull request with a concise description of the change.

Please do not include API keys, .env files, build artifacts, or live API responses containing sensitive data in commits or pull requests.

License

This project is licensed under the MIT License. See LICENSE.