flights-mcp

An MCP server for holiday flight planning powered by Google Flights via SerpAPI. Give any Claude-compatible AI assistant the ability to search real-time flight prices, discover destinations, compare airports, plan multi-country trips, and get booking links.

What it can do

Find airports

Resolve any place name — a city, region, or country — into airport IATA codes. Understands that "Nottingham" means East Midlands (EMA), that "London" covers six airports, that "Argentina" has a dozen options, and that "Patagonia" covers airports across both Argentina and Chile (BRC, USH, FTE, PUQ, NQN, CRD, REL, BBA).

Explore destinations

Open-ended holiday planning: "Where can I fly from East Midlands in June for under £500?" Returns destinations with flight prices, hotel prices, best travel dates, flight duration, and stops — all sourced from Google Travel Explore.

Also works for domestic route discovery: explore from AEP (Buenos Aires domestic) to see all Argentine destinations, or SCL to see Chilean routes.

Can filter by interest:

• Beaches (/m/0b3yr)
• Outdoors (/g/11bc58l13w)
• History (/m/03g3w)
• Museums (/m/09cmq)
• Skiing (/m/071k0)

Search flights

Full Google Flights search with every filter available:

• One-way, round-trip, or multi-city
• Economy through First class
• Nonstop only or max stops
• Specific airlines or alliances (Star Alliance, SkyTeam, Oneworld)
• Departure/arrival time windows
• Max price, max duration, layover duration
• Low-emission flights only
• Basic economy exclusion (US domestic)

Returns full flight details: price, duration, stops, airline, aircraft type, legroom, amenities, carbon emissions, and price insights (lowest price, typical range, price history).

Search across a date range

Find the cheapest day to fly: "When's the cheapest time to fly London to Buenos Aires in April?" Searches every date in a range and returns results sorted by price. Up to 30 days, one API call per date.

Compare departure airports

Find the cheapest airport to fly from: "Should I fly from East Midlands, Birmingham, or Manchester to Buenos Aires?" Looks up all airports near a location and searches from each one in parallel, returning a ranked price comparison.

Plan an open-jaw trip

Fly into one country and out of another without backtracking. Handles the full combination search automatically: finds all nearby departure airports, tries both directions (fly into Argentina/out of Chile vs fly into Chile/out of Argentina), and returns both options ranked by total combined price. Only 4 API credits regardless of how many airports are compared.

Check price insights

Get a quick read on whether prices for a route are currently cheap, typical, or expensive — without retrieving full flight listings. Returns the lowest recorded price, typical price range, price level, and a human-readable verdict (e.g. "Prices are 18% below typical — good time to book."). Uses 1 API credit.

Find cheapest arrival airport

The arrival-side counterpart to "compare departure airports". Resolves a destination like "Tokyo" or "Patagonia" to all nearby airports and searches each in parallel, returning a ranked list by price. Answers "Should I fly into EZE or AEP?" or "Which Patagonia airport is cheapest from London?". Uses one API credit per airport.

Find flights with a stopover

Search for a split itinerary via a hub city for a set number of days. "I want to fly London to Tokyo but spend 3 days in Dubai on the way — what are the cheapest options?" Searches origin → stopover and stopover → destination as separate one-way legs, optionally including a return leg too. Stopover location is resolved to airports automatically. Uses 2 API credits (3 with return).

Search a price calendar

Find the cheapest combination of departure and return dates for a round trip. "What's the cheapest week to fly London to New York in July?" Generates every (outbound, return) date pair from two date ranges and searches them all in parallel, returning results sorted by price with trip duration. Capped at 30 combinations. Uses 1 API credit per combination.

Plan a multi-stop trip

Chain together multiple legs for internal/domestic routing within a multi-country holiday. "I'm flying into Buenos Aires on Oct 17, want to visit Patagonia on Oct 23, then end in Santiago on Oct 28 — what are the cheapest flights for each leg?"

Location names are resolved to airports automatically — "Patagonia" becomes BRC, USH, FTE, PUQ, NQN, CRD, REL, BBA and a single search covers all of them. Returns the cheapest flight per leg plus up to 3 alternatives so you can compare specific airports (e.g. cheapest might be BRC/Bariloche but you can see FTE/El Calafate options for Perito Moreno). Uses N-1 API credits for N stops.

Get return flights

After finding an outbound flight, retrieve matching return options using the departure_token from the outbound result.

Get booking options

Get direct booking links from airlines and OTAs for a specific flight using the booking_token from any search result.

---

Tools

| Tool | Description | |------|-------------| | find_airports | Resolve a city/region/country to airport IATA codes | | explore_destinations | Discover where to fly and for how much | | search_flights | Full flight search with all filters | | search_flights_flexible | Find cheapest day to fly across a date range | | search_price_calendar | Find cheapest outbound + return date combination | | check_price_insights | Are prices cheap, typical, or expensive right now? | | compare_airport_prices | Compare prices from all departure airports near a location | | find_cheapest_arrival_airport | Compare prices into all arrival airports near a destination | | plan_open_jaw_trip | Fly into one country, return from another — find cheapest combo | | plan_multi_stop_trip | Plan internal legs of a multi-country trip | | find_stopover_flights | Split a long-haul via a stopover city for N days | | get_return_flights | Get return flights for a chosen outbound | | get_booking_options | Get booking links for a specific flight |

---

Setup

1. Get a SerpAPI key

Sign up at serpapi.com and get your API key. The free tier includes 100 searches/month.

2. Configure the environment

cp .env.example .env
# Edit .env and set your key:
# SERPAPI_KEYS=your_key_here

Multiple keys can be comma-separated for automatic rotation when one hits its quota:

SERPAPI_KEYS=key_one,key_two,key_three

3. Build

npm install
npm run build

4. Add to Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "flights": {
      "command": "node",
      "args": ["/absolute/path/to/flights-mcp/build/index.js"],
      "env": {
        "SERPAPI_KEYS": "your_serpapi_key_here"
      }
    }
  }
}

---

Example workflows

"Where's cheap to fly from Nottingham this summer?"

1. find_airports("Nottingham") → EMA, BHX, MAN, LHR, LGW, STN
2. explore_destinations(departure_id: "EMA,BHX,MAN", month: 7, travel_duration: 2) → ranked list of destinations with prices

"Cheapest way to get from Nottingham to Buenos Aires"

1. compare_airport_prices(location: "Nottingham", arrival_id: "EZE", outbound_date: "2026-06-01", return_date: "2026-06-15") → ranked by price across EMA, BHX, MAN, LHR, LGW

"When's cheapest to fly London to Tokyo in May?"

1. search_flights_flexible(departure_id: "LHR", arrival_id: "HND,NRT", date_from: "2026-05-01", date_to: "2026-05-31") → price per day sorted cheapest first

"Nottingham to Argentina and Chile in October, cheapest open-jaw"

1. plan_open_jaw_trip(departure_location: "Nottingham", destination_a: "Argentina", destination_b: "Chile", outbound_date: "2026-10-17", return_date: "2026-10-31") → compares EMA/BHX/MAN/LHR/LGW → EZE/AEP vs SCL, returns cheapest of: (UK→Argentina, Chile→UK) and (UK→Chile, Argentina→UK) with total prices

"Are London to Tokyo prices high right now?"

1. check_price_insights(departure_id: "LHR", arrival_id: "HND,NRT", outbound_date: "2026-07-15", return_date: "2026-07-29") → price level, typical range, context string

"Which Tokyo airport is cheapest to fly into from London?"

1. find_cheapest_arrival_airport(departure_id: "LHR", arrival_location: "Tokyo", outbound_date: "2026-07-15", return_date: "2026-07-29") → ranked comparison of NRT vs HND

"London to Tokyo but stop in Dubai for 3 nights"

1. find_stopover_flights(departure_id: "LHR", arrival_id: "NRT", outbound_date: "2026-07-15", stopover_location: "Dubai", stopover_days: 3, return_date: "2026-07-29") → LHR→DXB leg + DXB→NRT leg + NRT→LHR return

"Cheapest week to fly London to New York in July"

1. search_price_calendar(departure_id: "LHR", arrival_id: "JFK,EWR", outbound_date_from: "2026-07-01", outbound_date_to: "2026-07-14", return_date_from: "2026-07-10", return_date_to: "2026-07-31") → up to 30 (outbound, return) combinations sorted by price

"Buenos Aires to Patagonia to Santiago — internal legs"

1. plan_multi_stop_trip(trip: [{location: "Buenos Aires", date: "2026-10-17"}, {location: "Patagonia", date: "2026-10-23"}, {location: "Santiago", date: "2026-10-28"}]) → 2 API calls: AEP/EZE → BRC/USH/FTE/PUQ/NQN/CRD/REL/BBA, then those → SCL. Returns cheapest + alternatives per leg with total price.

"Argentina and Chile full trip"

1. plan_open_jaw_trip(...) → find cheapest UK ↔ Argentina/Chile international legs
2. plan_multi_stop_trip(...) → find cheapest internal legs between cities
3. get_booking_options(booking_token: "...") → direct booking links for each flight