Access Real-Time Aviation Data

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:

• modelcontextprotocol/servers
• punkpeye/awesome-mcp-servers
• glama
• smithery
• mcpservers.org

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

Prompts

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

Resources

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>"
      }
    }
  }
}

2. 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>"
      }
    }
  }
}

scripts/generate_server_card.py

"""Generate .well-known/mcp/server-card.json from the running server definition.

The card is a discovery document, so it has to match the tools, resources and
prompts the server actually exposes. Generating it keeps the two from drifting.
Run with --check in CI to fail when the committed card is stale.

The card deliberately carries no version. The release bot bumps pyproject on
its own, so a version here would desync on every release and fail the check.
"""

import argparse
import asyncio
import json
import sys
from pathlib import Path

from aviationstack_mcp.server import CONFIG_SCHEMA, mcp

REPO_ROOT = Path(__file__).resolve().parent.parent
CARD_PATH = REPO_ROOT / ".well-known" / "mcp" / "server-card.json"

DESCRIPTION = (
    "MCP server for Aviationstack flight, schedule, and aviation reference data."
)


async def _build_card() -> dict:
    """Introspect the server and assemble the card payload."""
    tools = await mcp.list_tools()
    resources = await mcp.list_resources()
    templates = await mcp.list_resource_templates()
    prompts = await mcp.list_prompts()

    resource_entries = [
        {
            "name": resource.name,
            "uri": str(resource.uri),
            "description": resource.description,
            "mimeType": resource.mimeType,
        }
        for resource in resources
    ]
    resource_entries += [
        {
            "name": template.name,
            "uriTemplate": template.uriTemplate,
            "description": template.description,
        }
        for template in templates
    ]

    return {
        "serverInfo": {
            "name": "aviationstack-mcp",
            "title": "Aviationstack MCP",
            "description": DESCRIPTION,
            "configSchema": CONFIG_SCHEMA,
        },
        "tools": [tool.model_dump(exclude_none=True) for tool in tools],
        "resources": resource_entries,
        "prompts": [prompt.model_dump(exclude_none=True) for prompt in prompts],
    }


def main() -> int:
    """Write the card, or verify the committed one is current."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--check",
        action="store_true",
        help="Exit non-zero if the committed card differs from the generated one.",
    )
    args = parser.parse_args()

    rendered = json.dumps(asyncio.run(_build_card()), indent=2) + "\n"

    if args.check:
        current = CARD_PATH.read_text(encoding="utf-8") if CARD_PATH.exists() else ""
        if current != rendered:
            print(
                f"{CARD_PATH.relative_to(REPO_ROOT)} is out of date. "
                "Run: python scripts/generate_server_card.py",
                file=sys.stderr,
            )
            return 1
        print(f"{CARD_PATH.relative_to(REPO_ROOT)} is up to date.")
        return 0

    CARD_PATH.parent.mkdir(parents=True, exist_ok=True)
    CARD_PATH.write_text(rendered, encoding="utf-8")
    print(f"Wrote {CARD_PATH.relative_to(REPO_ROOT)}")
    return 0


if __name__ == "__main__":
    sys.exit(main())