# Aviation MCP Server

MCP server giving AI agents access to real-time aviation data — live flight tracking, airport weather, airline and airport information.

## Features

| Tool | Description | Source |
|------|-------------|--------|
| `track_live_flights` | Current flights worldwide or in a specific area | OpenSky Network |
| `track_flight` | Track a specific flight by callsign or ICAO24 | OpenSky Network |
| `get_flight_path` | Historical flight path/trajectory | OpenSky Network |
| `get_airport_arrivals` | Recent arrivals at an airport | OpenSky Network |
| `get_airport_departures` | Recent departures from an airport | OpenSky Network |
| `get_airport_weather` | Current METAR weather at an airport | AviationWeather.gov |
| `get_weather_forecast` | TAF weather forecast for an airport | AviationWeather.gov |
| `get_aviation_warnings` | Active SIGMETs and aviation warnings | AviationWeather.gov |
| `get_airport_info` | Airport details (location, timezone, etc.) | AirLabs |
| `get_airline_info` | Airline details (fleet, hub, status) | AirLabs |

## Data Sources

- **OpenSky Network** — Live flight tracking, arrivals/departures, flight paths (no API key needed, 100 calls/day)
- **AviationWeather.gov** — METAR, TAF, SIGMETs (no API key needed, 100 req/min)
- **AirLabs** — Airport and airline database (free tier: 1,000 calls/month, API key required)

## Installation

### With pip

```bash
pip install aviation-mcp-server
```

### From source

```bash
git clone https://github.com/AiAgentKarl/aviation-mcp-server.git
cd aviation-mcp-server
pip install -e .
```

## Configuration

### API Keys

Copy `.env.example` to `.env` and add your keys:

```bash
cp .env.example .env
```

```env
# AirLabs — Optional (https://airlabs.co)
AIRLABS_API_KEY=your-key-here
```

> **Note:** OpenSky Network and AviationWeather.gov require no API key. The AirLabs key is only needed for `get_airport_info` and `get_airline_info`.

### Claude Desktop / Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "aviation": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "AIRLABS_API_KEY": "your-key-here"
      }
    }
  }
}
```

### Using uvx (no install needed)

```json
{
  "mcpServers": {
    "aviation": {
      "type": "stdio",
      "command": "uvx",
      "args": ["aviation-mcp-server"],
      "env": {
        "AIRLABS_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Usage Examples

**Track flights over Germany:**
> "Show me all flights currently over Germany"

**Check airport weather:**
> "What's the current weather at Frankfurt Airport?"

**Track a specific flight:**
> "Track Lufthansa flight DLH400"

**Get airport arrivals:**
> "Show me recent arrivals at JFK"

**Aviation warnings:**
> "Are there any active SIGMETs?"

## Airport Codes

This server uses **ICAO airport codes** (4 letters) for weather and flight data:

| Airport | IATA | ICAO |
|---------|------|------|
| Frankfurt | FRA | EDDF |
| Munich | MUC | EDDM |
| Berlin | BER | EDDB |
| New York JFK | JFK | KJFK |
| London Heathrow | LHR | EGLL |
| Paris CDG | CDG | LFPG |
| Tokyo Narita | NRT | RJAA |

## Rate Limits

| API | Limit | Auth |
|-----|-------|------|
| OpenSky Network | 100 calls/day (anonymous) | None |
| AviationWeather.gov | 100 requests/minute | None |
| AirLabs | 1,000 calls/month (free tier) | API Key |

## Tech Stack

- Python 3.11+
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP)
- httpx (async HTTP)
- OpenSky Network, AviationWeather.gov, AirLabs APIs

## License

MIT
