Skip to main content
Glama
flight-finder

flight-finder

by nstevens

flight-finder

Find the genuinely best flight — cash or points — by ranking every option against what a mile is actually worth to you.

Three ways to use this

  • 🧠 Build your own with Claude Code → GUIDE.md

  • 🛠 Run the code → below

  • 🚀 Just use it → hosted version (coming soon)

What it does

Award availability and cash fares live in a dozen places and change by the hour. flight-finder pulls both — cash fares (via Google Flights) and award space (via the seats.aero Pro API) — then ranks every option using your per-program cents-per-mile valuations and travel preferences. It also enriches each option with seat-quality detail from AeroLOPA — cabin layout, seat counts, and the actual seat map for the specific aircraft (tail-number matched) — so you're comparing the seat you'll actually sit in, not just the price. "Is this a good deal?" becomes a number, not a vibe. And it runs as an MCP server, so you can plan trips conversationally in Claude Code: "find me SEA→Tokyo in business under 120k points."

Related MCP server: PointsYeah MCP Server

Quickstart

uv sync
cp .env.example .env                      # add SEATS_AERO_API_KEY (+ optional AEROLOPA_API_ID / AEROLOPA_API_SECRET for seat maps)
# edit config/profile.yaml + config/programs.yaml (home airports, point balances, cpm values)
uv run ff search --from SEA --to FCO --depart 2026-11-21 --cabin BUSINESS
uv run ff awards --from SEA --to FCO --start 2026-11-18 --end 2026-11-23 --cabin business
uv run ff plan trips/example-trip.yaml --out trips/example-shortlist.md

MCP (Claude Code)

claude mcp add flight-finder --scope user \
  -- uv --directory /path/to/flight-finder run python -m flight_finder.mcp_server

Tools: search_cash_one_way, search_cash_round_trip, search_awards, find_positioning_flights, get_seat_map, plan_trip.

How it works

src/flight_finder/
  offer.py            # normalized Offer (cash or award) + Segment
  config.py           # profile + programs + env
  cash/                # Google Flights wrapper + multi-origin × date fan-out
  awards/              # seats.aero Pro client
  strategy/scorer.py   # cpm-based cost + preference-aware ranking  ← the core idea
  seatmaps/            # AeroLOPA enrichment: cabin product + seat map per aircraft (tail-matched)
  planner.py           # combines it all behind a TripSpec
  cli.py · mcp_server.py

The interesting decision: a single normalized Offer for cash and award, so the scorer can compare them on one axis — your dollar value — instead of apples-to-oranges price vs. miles.

What I learned building this

The hard part wasn't the model — it was the valuation layer. The same award seat is a steal or a trap depending on which points you hold, what you value, and even which seat you'll actually sit in. Encoding that judgment is what turns a search into a recommendation. It's true of most useful AI products: the model is the commodity; the context and the scoring are the moat.

Built with Claude Code

Built nights and weekends, mostly by talking to Claude — scaffolded, iterated, and tested through Claude Code.

License

MIT

Available Tools

6 tools
find_positioning_flightsA

Find positioning flights from from_city to return_hub near return_date. Useful for the asymmetric-return trick: main award returns from a hub (e.g. LHR); family needs to get there from Italy. Candidates must be verified as refundable on the airline site before booking.

Inputs: from_city (required), return_hub (required), return_date (required), earliest_days_before, +3 more.

get_seat_mapA

AeroLOPA cabin product + seat map URL for a specific aircraft.

Provide either `slug` (e.g. "ba-351") to skip resolution, or both
`carrier` (IATA, e.g. "BA") and `aircraft` (IATA code or displayed name).

Returns the structured CabinProduct dict — aircraft type, per-cabin pitch /
width / recline / amenities, free-text seat notes, and the
direct-CDN-cached seat map SVG URL. All cabins are included; pick the one
matching your offer cabin via `cabins[].cabin_type_name`.

Inputs: carrier, aircraft, slug.

plan_tripC

Run the full trip planner on a trips/*.yaml file.

Inputs: trip_yaml_path (required).

search_awardsD

Award search via seats.aero Pro API.

Inputs: origin_airports (required), destination_airports (required), start_date (required), end_date (required), +4 more. Returns: result

search_cash_one_wayC

Cash-fare one-way search via fli (Google Flights).

Inputs: origin (required), destination (required), depart_date (required), cabin, +6 more. Returns: result

search_cash_round_tripC

Cash-fare round-trip search via fli (Google Flights).

Inputs: origin (required), destination (required), depart_date (required), return_date (required), +5 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of flight finding: positioning flights, seat maps, trip planning, award search, and cash search (one-way and round trip). No overlaps.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., find_positioning_flights, get_seat_map, search_awards).

    Tool Count5/5

    Six tools cover the core functionality of a flight finder without excess. The scope is well-scoped and manageable.

    Completeness4/5

    The set covers major flight search types (award, cash) and trip planning, but lacks tools for flight status, booking management, or filtering by amenities. Minor gaps exist.

    Related MCP Connectors

    Related MCP Servers