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.

Personalization data (travelers, preferences, cards/points, companion groups, trip history) is stored server-side in the private flightclaw-api Worker (D1), reached via FLIGHTCLAW_API_URL + FLIGHTCLAW_API_KEY. Payment for bookings routes through Link virtual cards (duffel_book_with_link).

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

1. Get a bookable, payable offer with duffel_search_flights (real fares/ conditions). duffel_get_offer / duffel_get_seat_map for extras.
2. Confirm the choice with the user, then duffel_book_with_link with the group's passengers string. This creates a Link spend request (the user approves the charge, ≤ $500), returns a virtual card + Duffel checkout URL, and you complete payment via Chrome automation. For higher amounts use duffel_book_flight (Duffel balance) or duffel_create_checkout.
3. log_trip right after booking (route, dates, travelers, cabin, price, order_id) so it 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 (backend-backed)

• Travelers: save_traveler, list_travelers, get_traveler, delete_traveler, set_me, get_me, import_local_passengers (one-time migration of any old local data/passengers.json).
• 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.

Booking (Duffel) — duffel_search_flights, duffel_search_multi_city, duffel_get_offer, duffel_get_seat_map, duffel_book_flight, duffel_book_with_link, duffel_create_checkout, duffel_list_orders, duffel_get_order, duffel_request_change, duffel_confirm_change, duffel_cancel_order, duffel_confirm_cancel, duffel_check_alerts, link_list_payment_methods.

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

pip install flights "mcp[cli]"
export FLIGHTCLAW_API_URL="https://flightclaw-api.<your>.workers.dev"
export FLIGHTCLAW_API_KEY="<your API key>"
claude mcp add flightclaw -- python3 /path/to/flightclaw/server.py

The Worker (flightclaw-api) holds the Duffel token and D1 profile store; apply schema.sql once with wrangler d1 execute flightclaw-db --remote --file schema.sql.

Data

Personalization data is server-side (D1). Price-tracking history (data/tracked.json) and a local Duffel order cache (data/duffel_orders.json) remain local and are gitignored.