shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

flightclaw

Track flight prices using Google Flights data. Search flights, find cheapest dates, filter by airline/time/duration/price, track routes over time, and get alerts when prices drop. Also runs as an MCP server. Requires Python 3.10+ and the 'flights' and 'mcp' pip packages. Run setup.sh to install dependencies.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

flightclaw

FlightClaw is a personal travel-booking agent. It remembers who you are, who you travel with, the loyalty programs and cards you hold, and how you like to fly — then recommends, books, pays for, and learns from each trip.

Profiles, booking and payment run on the hosted server (https://mcp.flightclaw.com/mcp, OAuth sign-in). The local server in this repo only searches and price-tracks flights.

The flow

1. Onboarding (one time)

Set this up once, then reuse forever.

  1. Who you are — save_traveler for yourself (full passport-accurate name, DOB, contact, loyalty programmes), then set_me to mark that profile as you and record home airports.
  2. Companions — save_traveler for each person you travel with (relationship: spouse/partner/child/parent/friend/colleague). Group them with save_group (e.g. family = jack,jane).
  3. Preferences — set_preferences: cabin by haul (e.g. short-haul ECONOMY, long-haul BUSINESS), preferred/avoided airlines, alliance, seat, departure window, max stops, red-eye tolerance, baggage, meal, and budget sensitivity (cheapest / balanced / comfort).
  4. Cards & points — save_card for each card; set_points_balance for each loyalty/transfer program. Then enrich with the Card Links MCP (find_transfer_programs_for_airline, list_transfer_partners) so you know which airlines each card's points can reach.

2. Planning a trip

  1. Ask where they want to go and who's coming — reuse a group with get_group (it returns the exact passengers string for booking) or make a new one with save_group.
  2. Recommend — recommend_flights(origin, destination, date, ...). It loads the saved preferences, picks the cabin by haul, drops avoided airlines, and ranks options on price/duration/stops/preferred-airline/departure-window/ red-eye, returning the top 3 with a "why this fits you" for each.
  3. Awards / points option — if they want to spend points, call the Award Travel Finder MCP (search_availability, search_all_airlines, get_pricing) using their stored loyalty programs and points balances, and present award options alongside the cash fares ("best overall / cheapest / best points value").

3. Booking & paying

Hosted server (https://mcp.flightclaw.com/mcp)

  1. search_flights / search_multi_city / recommend_flights → pick an offer → get_offer to confirm price, bags and fare rules. Offers expire in about 30 minutes.
  2. Confirm the choice with the user, then create_checkout(offer_id, passengers). It returns checkout_id, checkout_url and the exact total_amount + total_currency (airline fare + FlightClaw booking fee). Nothing is charged yet.
  3. Pay one of two ways:
    • Checkout link — give the user checkout_url and total_amount. The user pays there by card.
    • Link virtual card — create a Link spend request for exactly total_amount in total_currency. The amount must include the booking fee; the fare alone is too low. The user approves the spend in Link. Then pay on checkout_url with the Link virtual card.
  4. get_checkout_status(checkout_id) until completed, then get_order. failed means no payment was taken and you can retry.

Payment rules:

  • Use the total_amount from create_checkout. Never compute the price yourself.
  • Never pay more than the amount the user approved in Link. If the total changes, stop, create a new checkout and ask for a new approval.
  • Never ask for or type card numbers from the user.

After booking, call log_trip (route, dates, travelers, cabin, price, order_id) so the trip enters history and the follow-up queue.

4. Post-trip follow-up & learning (the real magic)

  1. trips_pending_followup surfaces trips that have completed/returned.
  2. Ask how each went, then record_trip_feedback(id, feedback, learnings=...). Durable lessons (e.g. "prefers window on long-haul", "dislikes early departures") are appended to the user's preferences, so the next recommend_flights is sharper. Over time FlightClaw learns the traveler.

Tools

Personalization (hosted)

  • Travelers: save_traveler, list_travelers, get_traveler, delete_traveler, set_me, get_me.
  • Preferences: set_preferences, get_preferences, update_preferences.
  • Cards/points: save_card, list_cards, delete_card, set_points_balance, list_points.
  • Groups: save_group, list_groups, get_group, delete_group.
  • Trips: log_trip, list_trips, get_trip, trips_pending_followup, record_trip_feedback.
  • Recommendation: recommend_flights.

Search & tracking — search_flights, search_dates, track_flight, check_prices, list_tracked, remove_tracked.

Hosted booking — get_offer, get_seat_map, create_checkout, get_checkout_status, list_orders, get_order, request_change, cancel_order. Hosted price tracking: track_flight, list_tracked, remove_tracked (checked daily, email alert on a drop).

External MCP integration

FlightClaw stores the user's cards/points; the agent enriches and acts on them using two other MCP servers when present:

  • Card Links — transfer partners and card comparisons for the user's stored cards.
  • Award Travel Finder — award availability and points pricing across airlines/programs.

When surfacing card recommendations from Card Links, always include its disclaimers: not financial advice; affiliate links may earn commission; card terms change — verify current offers with the issuer.

Setup

Hosted: claude mcp add --transport http flightclaw https://mcp.flightclaw.com/mcp (sign in with OAuth; no keys needed).

Local (search and price tracking only, no account):

pip install "flights==0.9.0" "mcp[cli]<2" fastmcp pydantic-settings
claude mcp add flightclaw -- python3 /path/to/agents/server.py

Data

The local server stores price-tracking history in data/tracked.json (gitignored).