flights

A local MCP server for planning a trip from live public fares. It speaks stdio, needs no API key, and reads Google Flights pages through the unofficial fast-flights query builder. Airport names are resolved offline with airportsdata.

Defaults are 1 adult, economy, CHF.

Why this source

The constraint is a planner an agent can run with no paid account and no API key, and with no invented prices. The fields that matter are flight numbers, layovers, bags or fare family, a date window, and a fare that was actually returned.

Google is the one that still lets an agent compare real itineraries. The server says so when a field is missing. It does not fill bags in from legroom inches or from unnamed numeric flags on the payload.

Related MCP server: rihla

Run

From this directory, with uv:

uv sync
uv run flights-mcp

The same process is uv run python -m flights_mcp. A host that does not use uv can launch the module with whatever Python has the package installed:

python -m flights_mcp

The process is silent on stdout. MCP messages are the stdout stream. Logs go to stderr.

Example host config (Cursor, Claude Desktop, and anything else that launches a local stdio server):

{
  "mcpServers": {
    "flights": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/this/repo", "flights-mcp"]
    }
  }
}

No environment variables are required.

Tools

search_flights

Search live public fares across a short set of departure dates.

Pass depart_date, or depart_date with flexibility_days, or depart_from and depart_to. Not both an anchor and a from/to window. "Zurich to Barcelona, sometime in a week" is depart_from and depart_to seven days apart.

At most 7 departure dates are queried, one after another, inside 25 seconds. A longer window is sampled, including the first and last day, and the dates that were skipped are listed in dates_not_searched. A day that runs out of time is recorded on days and is not given an invented fare. nights does not search a grid of return dates. Each departure is one query.

Each itinerary includes:

• price and currency, as the integer Google returned

• airline names, local times, duration, stops, route, and each leg

• flight_numbers when Google sent them. A leg without one has flight_number: null and a note that says so

• layovers: airport and minutes. minutes_basis is google when the payload included the layover length, schedule when it was the gap between the leg times, and unknown when neither could be read. An empty layovers list means nonstop

• carry_on, checked_bag, and fare_family. On this source those are unknown / null, and fare_note says that nothing was assumed

• search_url for that date, and booking_url when Google attached a booking token. The booking link opens the itinerary on Google Flights. It is not a ticket

picks.cheapest, picks.fastest, and picks.compromise are itinerary ids. compromise is the option with the best even balance of price and duration among the flights that are not already the cheapest or the fastest. When the pool is too small for a distinct third option, it matches one of the other picks. The same id can carry more than one label. flights is sorted by price and always includes the three picks, up to max_results.

A city that matches several airports (Springfield) is an error. Pass an IATA code, or a metro code such as NYC. London and New York resolve to the metro code so the search covers the city's airports.

Unknown arguments are rejected. A failure is a tool error whose text contains JSON {"code","message",...}. Codes include unknown_place, ambiguous_place, invalid_input, no_results, unpriced, timeout, and upstream. An error never carries an invented price. A single day inside a window can also be skipped when its return would fall before departure.

resolve_airports

Offline IATA lookup.

Zurich and Zürich resolve to ZRH. Barcelona resolves to BCN (Barcelona in Venezuela is BLA; the airport named for the city is the one a search uses). NYC returns the metro code plus JFK and LGA. Newark is EWR.

Limits

• Fares are snapshots. They can change before anyone books.

• Bags and fare family are not on the itinerary Google returns to this parser. The fields are present so a planner can see the absence. They are never guessed.

• Times are local to each airport and have no offset. duration_basis is google when the payload included the trip duration, elapsed when it was computed from airport timezones, and air when only airborne minutes were available.

• For a round trip, price is the total Google showed for that departure and return. legs are the segments included in that result.

• The price is the integer Google returned, in the currency you asked for, in major units. It is not converted or rounded. Itineraries with no usable price are omitted. If none remain, the tool errors with unpriced.

• Identical searches in one process are reused for 2 minutes. The cache is memory only and includes the date window.

• Each day contributes at most 4 itineraries to the comparison: the cheapest ones, plus that day's fastest if it was not already among them. The overall list is still capped by max_results, and the labeled options are kept inside that cap.

• The whole search, including every date in the window, gets 25 seconds.

• At most two searches run at once.

Read SECURITY.md before pointing anything automated at this. fast-flights can break when Google changes the page, it can be rate limited, and automated access may violate Google's terms.

Tests

Offline tests cover schemas, validation, airport resolution, the page parser, date-window sampling, and a search that never leaves the machine:

uv run pytest

The live check is opt-in. It searches ZRH to BCN across seven days, one adult, economy, CHF, a few weeks out:

FLIGHTS_LIVE=1 uv run pytest tests/test_live.py -s

Live check

FLIGHTS_LIVE=1 uv run pytest tests/test_live.py on 2026-09-30. One-way ZRH to BCN, departures 2026-10-26 through 2026-11-01 (seven days, all searched), 1 adult, economy, CHF. The call wrote nothing to stdout. Every priced itinerary had carry_on and checked_bag set to unknown and fare_family null. Nothing was filled in.

Cheapest fare Google returned for each day:

The eight itineraries the tool returned (max_results 8), sorted by price. picks were the 48 CHF Vueling, the 54 CHF Vueling, and the 75 CHF SWISS.

Duration basis on these was google. The cheapest Vueling was an Airbus A320, with the carbon figure Google sent (83000 grams) and a booking URL. Fetching that booking URL from this environment returned HTTP 200 and the Google Flights page. It is not a held ticket. The booking token is not copied here.

The same parser, on the 2026-10-28 page alone, also saw connections. They did not make the shortlist: the nonstops above were cheaper, and the SWISS flight was faster, so the per-day keep (cheapest plus fastest) never held onto them. They are recorded because the layover fields were present:

Bags and fare family were absent on those connections too.

Search URL for the first day of the window:

https://www.google.com/travel/flights/search?tfs=GhoSCjIwMjYtMTAtMjZqBRIDWlJIcgUSA0JDTkIBAUgBmAEC&hl=en-US&curr=CHF

Treat the tables as a snapshot from that run.

Layout

• flights_mcp/server.py — MCP tools and stdio entrypoint

• flights_mcp/search.py — date window, labels, timeout, cache

• flights_mcp/google_parse.py — flight numbers, layovers, and prices from the page

• flights_mcp/dates.py — the 7-date cap

• flights_mcp/upstream.py — one bounded Google Flights fetch

• flights_mcp/airports.py — local IATA lookup

• flights_mcp/models.py — strict input and output schemas