Flightclaw

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).

WiFi — check_flight_wifi(flight_number): use when the user asks whether a specific flight (e.g. UA1234) has WiFi or Starlink. Call it only for flights the user cares about, not for every search result. Quote the attribution (seatwifi.com) when you relay the answer.

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):

bashCopy code
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).