# 🛩️ Flight MCP Server

> **Real-time flight tracking for LLMs** — Connect any AI assistant to live aircraft data from ADS-B Exchange

Transform your AI conversations with live flight intelligence. Search aircraft by location, track specific flights, monitor military activity, and discover aviation patterns — all through a clean MCP interface.

## 🚀 Quick Start

**1. Setup**
```bash
bun install && bun run build
```

**2. Get API Key**
- Subscribe to [ADS-B Exchange on RapidAPI](https://rapidapi.com/adsbx/api/adsbexchange-com)
- Add key to `.env`: `RAPIDAPI_KEY=your_key_here`

**3. Test with Inspector**
```bash
bun run inspect
```

## 🛠 API Tools

```python
# Search aircraft around coordinates
search_aircraft(lat=40.7128, lon=-74.0060, radius_nm=25)
# → Aircraft within 25nm of NYC

# Get specific aircraft details  
get_aircraft(hex="a4b065")
# → Full aircraft data by ICAO code

# Browse military aircraft with filters
list_military_aircraft(
  region="us",           # us/europe/asia/all
  aircraft_type="H60",   # helicopters/cargo/fighters
  min_altitude=1000,     # exclude ground traffic
  limit=20,              # per page
  page=2                 # pagination
)

# Discover available aircraft types
get_military_aircraft_types(region="us")
# → Available types: H60, C17, F35, etc.
```

## 📊 Example Response

```json
{
  "hex": "a4b065",
  "callsign": "NKS185",
  "position": {"lat": 51.470, "lon": -0.456},
  "altitude": 38000,
  "speed": 460,
  "heading": 275
}
```

## 🎯 Use Cases

- **Flight tracking**: Monitor specific aircraft or routes
- **Aviation research**: Analyze traffic patterns and aircraft types  
- **Military monitoring**: Track defense aircraft activity by region
- **Location intelligence**: Find aircraft near points of interest
- **Real-time alerts**: Build notifications for aircraft events

**Rate limits apply** • **4-second minimum polling** • **Powered by ADS-B Exchange**