<div align="center">

✈️ flight-search-mcp

A Model Context Protocol server for live flight tracking — built with the official MCP Python SDK, powered by a genuinely free API.

Give Claude (or any MCP client) the ability to look up live flights, check real-time status, and resolve airport/airline codes — no paid API, no credit card.

</div>

---

What this does

Ask your MCP client things like:

"Is flight BA100 delayed?" "What flights are currently in the air from JFK to LHR?" "What's the IATA code for Heathrow?"

...and it answers with real, live data pulled straight from AviationStack.

Why AviationStack

AviationStack is the one that's still genuinely free for indie developers: ~100 requests/month, no credit card, API key in seconds.

The trade-off: the free plan covers current & near-term live flights only — no future-dated trip search, no historical data, no fares. This is a flight tracker, not a trip planner. If you outgrow that, see Scope & limitations below.

✨ Features

• 🔍 search_flights — live flights by route, airline, or status
• 📡 get_flight_status — real-time status, gate, delay, live position for one flight
• 🛫 resolve_airport — city/airport name → IATA code
• 🏢 resolve_airline — airline name → IATA code
• ⚡ Smart caching — protects your monthly quota automatically
• 🛡️ Input validation with actionable error messages, not raw API errors
• ✅ Tested, typed, and small enough to actually read

🚀 Quickstart

git clone https://github.com/PythonicMind2/flight-search-mcp.git
cd flight-search-mcp
pip install -e .

cp .env.example .env
# paste your free AviationStack key into .env — get one at
# https://aviationstack.com/signup/free (instant, no card)

python -m flight_search_mcp.server

Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flight-search": {
      "command": "python",
      "args": ["-m", "flight_search_mcp.server"],
      "cwd": "/absolute/path/to/flight-search-mcp",
      "env": {
        "AVIATIONSTACK_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Claude Desktop and ask it about a flight.

🧰 Tools

Tool	Args	Returns
search_flights	origin?, destination?, airline_name?, flight_status?, max_results?	Live flights matching at least one filter
get_flight_status	flight_iata (e.g. "BA100")	Status, gate, delay, live position
resolve_airport	keyword (city or airport name)	Matching IATA codes
resolve_airline	keyword (airline name)	Matching IATA codes

search_flights requires at least one of origin, destination, or airline_name — an unfiltered call would burn quota on an arbitrary global sample.

🏗️ Project structure

flight-search-mcp/
├── src/flight_search_mcp/
│   ├── server.py               # FastMCP server + tool definitions
│   ├── aviationstack_client.py # Async API client, caching, error handling
│   ├── models.py                # Pydantic response models
│   ├── cache.py                 # Minimal in-memory TTL cache
│   └── config.py                # Env-based settings
├── tests/test_server.py         # Parsing + validation tests (no network)
├── .github/workflows/tests.yml  # CI
├── .env.example
└── pyproject.toml

Design choices worth knowing about:

• Auth is a plain access_key query param — no OAuth token juggling.
• Caching is tiered: reference data (airports/airlines) is cached for an hour since it barely changes; live flight data for 30 seconds, mainly to absorb accidental duplicate calls in the same turn. Every cache hit is a request you don't spend against your ~100/month quota.
• Errors: AviationStack often returns HTTP 200 with an "error" object in the body instead of a 4xx. The client catches this and raises a real exception with a useful hint (quota exhausted, wrong key, paid-only feature) instead of silently returning nothing.

🧪 Testing

pip install pytest pytest-asyncio
pytest tests/ -v

All tests run against sample payloads — no API key or network access needed.

⚠️ Scope & limitations

AviationStack's free plan does not include:

• Future-dated trip search (/flightsFuture is paid-only)
• Historical flights beyond the current window
• /routes (date-independent schedule lookups — paid-only)
• Any pricing/fare data (AviationStack doesn't do fares on any plan)
• The search autocomplete param on /airports//airlines (this repo works around it by filtering one reference page client-side)

If you need real future-dated search with prices, look at FlightAPI.io (small free trial, then paid) or Duffel (free sandbox data forever, real data is pay-per-use). PRs adding either as an optional second backend are welcome.

🤝 Contributing

Issues and PRs welcome. Keep it small, keep it tested.

<div align="center"> Built with the <a href="https://github.com/modelcontextprotocol/python-sdk">official MCP Python SDK</a>. </div>