flightaware-mcp 0.0.1

MCP Server exposing the FlightAware AeroAPI via the Model Context Protocol.

FlightAware MCP

• Setup
  • Local
  • Remote
• Configure
• Development
• Building
• Support
• Contributing

MCP Server exposing the FlightAware AeroAPI via the Model Context Protocol.

You need a Free API Key to use this MCP.

Features

• List Flights by ICAO or IATA Flight Number
• Accurately Convert IATA to ICAO Flight Numbers
• Response Caching with Configurable TTL

Setup

This can be run in Local CLI mode or Remote server mode.

Local

In CLI mode using uv.

View Config - Local uv

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flightaware": {
      "type": "local",
      "command": ["uvx", "flightaware-mcp"],
      "environment": {
        "AEROAPI_KEY": "xxx"
      }
    }
  }
}

In CLI mode using Python pip.

pip install flightaware-mcp

View Config - Local Python

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flightaware": {
      "type": "local",
      "command": ["flightaware-mcp"],
      "environment": {
        "AEROAPI_KEY": "xxx"
      }
    }
  }
}

Remote

With Docker run.

docker run --rm -p 80:8000 -e AEROAPI_KEY=${AEROAPI_KEY} ghcr.io/cssnr/flightaware-mcp:latest

With Docker Compose.

services:
  app:
    image: ghcr.io/cssnr/flightaware-mcp:latest
    ports:
      - '80:8000'
    environment:
      AEROAPI_KEY: ${AEROAPI_KEY}

With Python from source.

uv sync
export AEROAPI_KEY=${AEROAPI_KEY}
uv run uvicorn flightaware_mcp.server:app --app-dir src --host 0.0.0.0 --port 8000

View Config - Remote

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flightaware": {
      "type": "remote",
      "url": "http://localhost/mcp"
    }
  }
}

Note: Set the url to the host you are running the server on.

For a Docker Swarm + Traefik example see the docker-compose-swarm.yaml.

For a Portainer Deploy workflow see the .github/workflows/deploy.yaml.

Configure

Variable	Description
AEROAPI_KEY	FlightAware API Key
HISHEL_CACHE_PATH	Cache DB Path
HISHEL_CACHE_TTL	Cache TTL

You only need AEROAPI_KEY the rest are for advanced configuration.

Development

Sync project.

uv sync

Run local server.

run cli

Run remote server (live reload).

run dev

Point your client to: http://localhost:8000/mcp

Run remote Docker Compose (live reload).

run compose

Point your client to: http://localhost/mcp

You can set the PORT environment variable.

Building

Docker Image

To build and test the docker image run.

bash build.sh
docker compose up

Point your client to: http://localhost/mcp

Python Package

This builds the bdist and wheel, if you have a use for it...

run build

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/flightaware-mcp/issues
• Q&A Discussion: https://github.com/cssnr/flightaware-mcp/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/flightaware-mcp/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/