Pradumnasaraf/aviationstack-mcp

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

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

License

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