Skip to main content
Glama
Sign In

Google Flights MCP

by ai.wondel
OverviewDiscussionsAdmin

Search Google Flights (SerpAPI)

google_flights_search

Search Google Flights live via SerpAPI. Returns best_flights and other_flights (each with legs, airlines, times, duration, layovers, price and carbon emissions), plus price_insights and airport info. Supports round trip (type=1, needs return_date), one way (type=2) and multi-city (type=3 via multi_city_json). Two-step flows: pass a departure_token from a prior result to get the returning flights / next leg, or a booking_token to get booking options — re-send the original search params alongside either token. Prices are in currency (default USD). IDs are AIRPORT codes, never city/metro codes: TYO, NYC, LON, PAR, MIL, ROM, OSA, CHI, WAS return NO results (live-verified) — send the airports instead (TYO → 'HND,NRT'; NYC → 'JFK,EWR,LGA'; LON → 'LHR,LGW,STN,LTN'; PAR → 'CDG,ORY'; MIL → 'MXP,LIN,BGY'; ROM → 'FCO,CIA') or the city's Google kgmid (e.g. '/m/07dfk' for Tokyo). Result shape: { note?, source, fetchedAt, query, search_metadata: { google_flights_url }, search_parameters, best_flights: [...], other_flights: [...], price_insights, airports } — the two itinerary lists are best_flights and other_flights (there is no flights or deals key at the top level, and an itinerary is never a bare flight). Each itinerary: { flights: [{ departure_airport: { name, id, time }, arrival_airport: { name, id, time }, duration, airplane, airline, airline_logo, travel_class, flight_number, legroom, extensions }], layovers: [{ duration, name, id, overnight }], total_duration, carbon_emissions, price, type, airline_logo, departure_token, booking_token } — price is the whole-itinerary price in currency, duration/total_duration are minutes, and the per-leg times are local 'YYYY-MM-DD HH:MM' strings. Feed departure_token back for the return leg and booking_token for booking options. A top-level note appears only when stops=1 found no nonstop flight and the server retried without the stop filter: the itineraries are then connecting flights, and their tokens need the same params re-sent without stops — tell the user that no direct flights were found and connecting flights are shown.

Input Schema

NameRequiredDescriptionDefault
glNoCountry code for the search, e.g. 'us', 'uk', 'de'.
hlNoLanguage code, e.g. 'en', 'es', 'fr'.
bagsNoNumber of carry-on bags. Default 0.
typeNoTrip type: 1 = round trip (default), 2 = one way, 3 = multi-city.
stopsNoMax stops: 0 = any (default), 1 = nonstop only, 2 = 1 stop or fewer, 3 = 2 stops or fewer. When stops=1 finds no nonstop flight, the server automatically retries without the filter and returns connecting flights with a `note`; send a departure_token/booking_token from those with the same params but no stops.
adultsNoNumber of adults. Default 1.
sort_byNoSort order: 1 = top flights (default), 2 = price, 3 = departure time, 4 = arrival time, 5 = duration, 6 = emissions.
childrenNoNumber of children. Default 0.
currencyNoCurrency of returned prices (ISO code, e.g. 'USD', 'EUR'). Default USD.
no_cacheNoForce a fresh SerpAPI fetch and bypass this server's result cache. Default false.
emissionsNoEmissions filter: 1 = less emissions only. Omit for no filter.
max_priceNoMaximum ticket price in the selected currency.
arrival_idNoArrival AIRPORT IATA code(s) (e.g. 'HND,NRT') or a Google location kgmid (e.g. '/m/07dfk' for Tokyo). Comma-separate multiple. NOT a city/metro code — TYO, LON, PAR, MIL, ROM, OSA return no results; list the airports instead.
zero_traceNoEnterprise-only ZeroTrace mode: don't store search params/metadata on SerpAPI. Default false.
deep_searchNoRun a deeper search that matches the Google Flights browser results more closely (slower). Default false.
return_dateNoReturn date, YYYY-MM-DD. Required when type=1 (round trip).
show_hiddenNoInclude hidden flight results. Default false.
departure_idNoDeparture AIRPORT IATA code(s) (3-letter, uppercase, e.g. 'WAW' or 'WAW,WMI') or a Google location kgmid (/m/… or /g/…). Comma-separate multiple. NOT a city/metro code — TYO, NYC, LON, PAR, MIL, ROM return no results; list the airports instead (NYC → 'JFK,EWR,LGA'). Used for type 1/2; for multi-city (type 3) use multi_city_json instead.
max_durationNoMaximum total trip duration in minutes (e.g. 1500 for 25h).
return_timesNoReturn time window, same format as outbound_times. Only valid when type=1.
travel_classNoTravel class: 1 = economy (default), 2 = premium economy, 3 = business, 4 = first.
booking_tokenNoToken from a prior result, used to fetch booking options for a selected itinerary. Re-send the same search params alongside it. Mutually exclusive with departure_token.
exclude_basicNoExclude basic-economy fares. Only for domestic US flights with travel_class=1. Default false.
exclude_connsNoConnecting airports to exclude: comma-separated 3-letter IATA codes (e.g. 'CDG,LHR').
outbound_dateNoOutbound date, YYYY-MM-DD.
infants_on_lapNoNumber of infants on lap. Default 0.
outbound_timesNoOutbound time window as comma-separated hours (0-23). 2 values = departure range 'min,max' (e.g. '4,18'); 4 values add an arrival range (e.g. '4,18,3,19').
departure_tokenNoToken from a prior result, used to select an outbound flight and fetch the returning flights (round trip) or the next leg (multi-city). Re-send the same search params alongside it. Mutually exclusive with booking_token.
infants_in_seatNoNumber of infants in seat. Default 0.
multi_city_jsonNoMulti-city itinerary (required when type=3): a JSON-string array of legs, e.g. '[{"departure_id":"CDG","arrival_id":"NRT","date":"2026-06-27"},{"departure_id":"NRT","arrival_id":"LAX","date":"2026-07-03"}]'. Each leg may include an optional "times" field (same format as outbound_times).
exclude_airlinesNoExclude these airlines: comma-separated 2-letter IATA codes, or an alliance (STAR_ALLIANCE, SKYTEAM, ONEWORLD). Mutually exclusive with include_airlines.
include_airlinesNoOnly these airlines: comma-separated 2-letter IATA codes, or an alliance: STAR_ALLIANCE, SKYTEAM, ONEWORLD. Mutually exclusive with exclude_airlines.
layover_durationNoLayover duration range in minutes, 'min,max' (e.g. '90,330' for 1.5-5.5h).

Output Schema

NameRequiredDescriptionDefault
noteNoPresent only when stops=1 found no nonstop flight and best_flights/other_flights are connecting flights from a search without the stop filter. Tell the user that no direct flights were found, so connecting flights are shown.
queryYes
sourceYes
airportsNo
fetchedAtYes
best_flightsNo
other_flightsNo
price_insightsNo
search_metadataNo
search_parametersNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses the auto-retry behavior behind a top-level `note` when stops=1 finds no nonstop, the meaning of departure_token vs booking_token, and the mutually-exclusive token usage. It omits auth/environment constraints and caching behavior beyond what the schema's no_cache parameter states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and logically ordered, but bloated: a full result-shape and per-itinerary field listing is spelled out even though an output schema already exists, and the metro-code warning is repeated three times (top-level, departure_id, arrival_id). Several sentences re-state schema-documented defaults (currency USD).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 33-parameter search tool with no annotations, the description covers the operationally risky parts: token round-trips, the stops retry note, unit conventions (minutes, local times), and the metro-code trap. The only real gap is sibling differentiation against google_flights_deals_search; the extensive result-shape prose compensates for the absence of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline would be 3, but the description adds cross-parameter meaning the schema cannot: return_date is required only for type=1, multi-city legs go in multi_city_json rather than departure_id/arrival_id, and tokens must be accompanied by the original search params. The airport-vs-metro-code warning with concrete mappings is genuinely useful, though it largely duplicates the departure_id/arrival_id schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Search Google Flights live via SerpAPI') and immediately enumerates what comes back (best_flights, other_flights, price_insights, airports). It also preempts a likely confusion by naming the exact top-level keys that do NOT exist ('no `flights` or `deals` key'), which separates it in spirit from the deals sibling even though that sibling is not named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly maps the three trip types to their required inputs (type=1 needs return_date, type=3 uses multi_city_json) and describes the two-step token flows with the requirement to re-send original params. It does not mention the sibling google_flights_deals_search or say when a user should prefer it over this tool, so the alternative-routing half of the guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Google Flights MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources