mikedarke/mcp-server-flight-aware-aeroapi

FlightAware AeroAPI MCP Server

A Model Context Protocol (MCP) server that provides access to FlightAware's AeroAPI for flight tracking and aviation data.

Overview

This MCP server exposes FlightAware's AeroAPI endpoints as MCP tools, allowing AI assistants to:

• Search for flights using various criteria
• Get real-time flight positions and tracking data
• Access airport information, delays, and weather
• View flight routes and generate track maps
• Submit flight intents and manage flight data

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

API Access

This server requires a valid FlightAware AeroAPI subscription. Visit FlightAware AeroAPI to sign up and obtain an API key.

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "flightaware": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/flight-aware",
      "env": {
        "FLIGHTAWARE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage

Start the server:

npm start

Or run in development mode:

npm run dev

Available Tools

FlightService Tools (11 total)

Flight Search

• search-flights - Search flights with simple syntax (-key value)
• search-flights-advanced - Search flights with advanced operators ({operator key value})
• search-flight-positions - Search flight positions with geospatial filters
• count-flights - Get count of flights matching criteria

Flight Information & Tracking

• get-flight - Get comprehensive flight information by identifier
• get-flight-canonical - Resolve ambiguous flight identifiers
• get-flight-position - Get current position of specific flight (requires fa_flight_id)
• get-flight-track - Get complete flight path history (requires fa_flight_id)
• get-flight-route - Get filed flight route with waypoints (requires fa_flight_id)
• get-flight-map - Generate flight track map image (requires fa_flight_id)

AirportService Tools (16 total)

Airport Information

• get-airport - Get static airport information (name, location, timezone)
• get-nearby-airports - Find airports near geographic coordinates
• get-airport-canonical - Resolve ambiguous airport codes
• get-all-airports - Get list of all known airports

Flight Activity

• get-airport-flights - Get all recent/upcoming flights for airport
• get-airport-arrivals - Get recent arrivals at airport
• get-airport-departures - Get recent departures from airport
• get-scheduled-arrivals - Get future scheduled arrivals
• get-scheduled-departures - Get future scheduled departures
• get-airport-flight-counts - Get flight count statistics
• get-flights-between-airports - Get flights between specific airports
• get-airport-routes - Get route information between airports

Airport Conditions

• get-airport-delays - Get delay information for specific airport
• get-all-airport-delays - Get delays for all airports with current delays
• get-airport-weather - Get current weather observations
• get-airport-weather-forecast - Get weather forecast

Quick Examples

Find United flights to Los Angeles:

{
  "tool": "search-flights",
  "parameters": {
    "query": "-airline UAL -destination KLAX"
  }
}

Find high-altitude flights:

{
  "tool": "search-flights-advanced",
  "parameters": {
    "query": "{> alt 350}"
  }
}

Get airport information:

{
  "tool": "get-airport",
  "parameters": {
    "id": "KLAX"
  }
}

Track specific flight:

{
  "tool": "get-flight-position",
  "parameters": {
    "id": "UAL123-1234567890-airline-0123"
  }
}

Common Error Prevention

❌ Wrong Syntax for Tool

// DON'T mix syntaxes
{
  "tool": "search-flights",
  "parameters": {
    "query": "{= dest KLAX}"  // Wrong! Use "-destination KLAX"
  }
}

❌ Wrong Identifier Type

// DON'T use flight ident for tracking
{
  "tool": "get-flight-position",
  "parameters": {
    "id": "UAL123"  // Wrong! Need fa_flight_id from search first
  }
}

✅ Correct Workflow

1. Search for flight: search-flights with "-idents UAL123"
2. Extract fa_flight_id from results
3. Track flight: get-flight-position with fa_flight_id

Data Limitations

• Flight search functions return data from approximately the last 24 hours
• Historical data beyond 10 days requires separate historical endpoints
• Some route decoding may not work for flights outside continental US airspace
• Flight intent submission requires special account permissions

Development

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Run tests (when available)
npm test

# Clean build directory
npm run clean

API Documentation

• FlightAware AeroAPI: Official Documentation
• OpenAPI Specification: Available in aeroapi-openapi.yml
• Tool Examples: See examples.md for 40+ practical usage examples

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the service-based architecture pattern
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

License

This project is licensed under the ISC License.