✈️ Flight Tool MCP Server

A lightweight MCP (Model Context Protocol) server that exposes real-time flight search as a tool for any MCP-compatible AI agent — Claude, LangGraph, or any other MCP client.

Built on top of the AviationStack API using FastMCP.

---

What it does

flowchart LR
    A["MCP Client<br/>(Claude / LangGraph Agent)"] -->|"tools/call<br/>search_flights"| B["Flight Tool<br/>MCP Server"]
    B -->|"GET /v1/flights"| C["AviationStack API"]
    C -->|"live flight data"| B
    B -->|"structured JSON result"| A

    style A fill:#1f6feb,color:#fff
    style B fill:#238636,color:#fff
    style C fill:#9e6a03,color:#fff

Give it a departure and arrival airport (IATA code), and it returns real-time flight data — airline, flight number, scheduled/actual times, and status (scheduled, active, landed, cancelled).

---

Tool: search_flights

Parameter	Type	Required	Description
dep_iata	str	✅	Departure airport IATA code, e.g. "BBI" (Bhubaneswar)
arr_iata	str	✅	Arrival airport IATA code, e.g. "DEL" (Delhi)

Returns:

{
  "success": true,
  "count": 40,
  "flights": [
    {
      "airline": "IndiGo",
      "flight_number": "6E6176",
      "departure_airport": "Bhubaneswar",
      "departure_time": "2026-08-10T15:40:00+00:00",
      "arrival_airport": "Indira Gandhi International",
      "arrival_time": "2026-08-10T18:00:00+00:00",
      "status": "scheduled"
    }
  ]
}

Note: Only real-time/current flight data is supported on the free AviationStack tier — no historical or future-dated search. A flight_date filter was originally planned but dropped, since date-based queries aren't reliably supported on the free plan.

---

Setup

1. Clone and install dependencies

pip install fastmcp requests python-dotenv

2. Add your API key

Create a .env file:

AVIATIONSTACK_API_KEY=your_aviationstack_key_here

Get a free key at aviationstack.com.

3. Run locally

python main.py

By default this runs over stdio, ready to be picked up by any local MCP client (e.g. Claude Desktop config, MCP Inspector).

---

Deploying to Render

Switch the transport to SSE/HTTP so it can run as a persistent web service:

if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8000)

Then on Render:

1. Create a new Web Service, connect this repo
2. Set the start command: python main.py
3. Add AVIATIONSTACK_API_KEY under Environment Variables
4. Deploy — your MCP server will be live at https://your-service.onrender.com

---

Free-Tier Constraints (AviationStack)

Keep these in mind while extending this server:

• ✅ http:// only — https:// is not supported on the free plan
• ✅ /v1/flights (real-time data) works on free tier
• ❌ /v1/routes, /v1/airports, /v1/airlines return function_access_restricted — paid plans only
• ❌ Historical / future flight_date filtering is unreliable on free tier
• ⚠️ 100 requests/month limit — test sparingly

---

Tech Stack

• FastMCP — MCP server framework
• AviationStack API — live flight data
• Requests — HTTP client
• python-dotenv — environment config

---

Roadmap

• [ ] Deploy to Render as a persistent SSE endpoint
• [ ] Wire into Trip-Friend's LangGraph flight_agent via langchain-mcp-adapters
• [ ] Add guardrails (rate limiting, input validation)
• [ ] Explore paid-tier upgrade for route/airport lookup tools

---

License

See LICENSE.