llms.txt

# trvl

> AI travel MCP server and CLI for Google Flights, Google Hotels, Booking.com, Trivago, Airbnb, Hostelworld, HomeToGo, trains, buses, ferries, door-to-door multimodal itineraries, price alerts, award travel, and travel-hack detection.

trvl is a single Go binary for AI assistants and terminal users. It searches flights, hotels, ground transport, destinations, airport transfers, price watches, and trip plans with a 1-tool MCP router plus compatibility aliases. Default use needs no personal API keys. Most providers use public HTTP/JSON endpoints; a few protected providers use explicit browser/cookie/curl fallbacks when enabled.

Trust boundary for hotels: use `search_accommodations` for traveller-facing stay recommendations. `search_hotels` is a discovery search. Google Hotels-style prices can be lead-in or teaser rates and must not be treated as checkout-final. For public recommendations, ranked offers should come from criteria-matched `search_accommodations` results or from shortlisted hotels verified with `search_hotels_with_details`, `hotel_rooms`, or `trvl serpapi` and ranked on room-level `total_price`/tax-inclusive provider totals when present. trvl surfaces booking/provider links for manual booking handoff; it does not book, hold, or guarantee a rate.

## Install

curl -fsSL https://github.com/MikkoParkkola/trvl/releases/latest/download/trvl_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz -C /usr/local/bin trvl

## MCP Server Setup (for AI assistants)

Command: trvl mcp
Transport: stdio

Claude Code: claude mcp add trvl --transport stdio -- trvl mcp
Claude Desktop: Add {"mcpServers":{"trvl":{"command":"trvl","args":["mcp"]}}} to config

## Skills (install after MCP setup)

mkdir -p ~/.claude/skills
for s in trvl providers; do
  curl -fsSL "https://raw.githubusercontent.com/MikkoParkkola/trvl/main/.claude/skills/$s.md" -o "$HOME/.claude/skills/$s.md"
done

## MCP Tools (1 smart tool + compatibility aliases)

- search_flights(origin, destination, departure_date, [return_date, cabin_class, max_stops, sort_by, alliances, depart_after, depart_before, less_emissions, carry_on_bags, checked_bags, require_checked_bag, max_price, max_duration, exclude_basic, airlines])
  - checked_bags: HIDDEN GOOGLE FEATURE — server-side filter not exposed in Google's own UI
- search_dates(origin, destination, start_date, end_date, [trip_duration, is_round_trip])
- search_accommodations(location, check_in, check_out, [adults, children_ages, guests, accommodation_type, amenities, preferred_amenities, neighborhoods, max_total_price, refundable_required, free_cancellation, property_type, room_type, min_bedrooms, min_bathrooms, min_beds, must_have_kitchen, must_have_wifi, must_have_workspace, max_candidates, max_offers])
  - Traveller-first room/apartment search. Ranked `offers` are matched room-level prices for the requested criteria; discovery lead-in prices stay under `candidates`.
- search_hotels(location, check_in, check_out, [guests, stars, sort, currency, free_cancellation, property_type, brand, min_rating, max_distance, amenities, min_price, max_price, enrich_amenities, eco_certified])
  - Discovery/ranking search. Treat prices as lead-in until verified with room/detail/provider totals.
  - free_cancellation: server-side Google Hotels ?fc=1 param
  - property_type: hotel|apartment|hostel|resort|bnb|villa — server-side ?ptype=N
  - brand: chain name substring — client-side
  - min_rating/max_distance/min_price/max_price: server-side + client-side guard
  - eco_certified: boolean (default false) — only show eco-certified hotels with sustainability certifications — server-side &ecof=1
- hotel_prices(hotel_id, check_in, check_out, [currency])
  - Provider price comparison when Google exposes booking partners. Prefer criteria-matched offers from `search_accommodations` or room-level totals from `hotel_rooms`/`search_hotels_with_details` for booking decisions.
- hotel_reviews(hotel_id, [limit, sort])
- hotel_rooms(hotel_name, check_in, check_out, [currency, booking_url])
  - Verification drill-down for room availability, cancellation, board, nightly price, total price, and taxes/fees when providers expose them.
- watch_room_availability(hotel_name, check_in, check_out, [currency])
- search_hotel_by_name(name, check_in, check_out, [location, currency])
  - Searches for a specific hotel by name across all providers (Google Hotels, Trivago, Booking, Airbnb, Hostelworld). Fuzzy-matches results to the search name. Ideal for finding a known property.
- destination_info(location, [travel_dates])
- calculate_trip_cost(origin, destination, depart_date, return_date, [guests, currency])
- weekend_getaway(origin, month, [max_budget, nights])
- suggest_dates(origin, destination, target_date, [flex_days, round_trip, duration])
- optimize_multi_city(home_airport, cities, depart_date, [return_date])
- search_ground(from, to, date, [currency, type, max_price, provider, allow_browser_fallbacks])
  - type: bus|train|ferry
- search_airport_transfers(airport_code, destination, date, [arrival_time, currency, type, max_price, provider])
- nearby_places(location, [type, radius])
- travel_guide(location)
- local_events(location, start_date, end_date)
- search_restaurants(location, [cuisine, price_level])
- search_deals([origin, max_price, type])
- plan_trip(origin, destination, depart_date, return_date, [currency, guests])
- search_route(from, to, arrive_by, [avoid, currency])
- get_weather(location, [days])
- get_preferences()
- update_preferences(field, value, ...)
- detect_travel_hacks(origin, destination, date, [return_date, carry_on_only])
- detect_accommodation_hacks(location, check_in, check_out)
- search_natural(query)
- find_trip_window(origin, destination, start_month, end_month, busy_intervals)
- list_trips()
- get_trip(trip_id)
- create_trip(name)
- add_trip_leg(trip_id, type, ...)
- mark_trip_booked(trip_id, leg_index)
- export_ics(trip_id)
- get_baggage_rules(airline, [type])
- build_profile() — build traveller profile from booking history (email parsing + LLM)
- add_booking(type, provider, [reference], [notes]) — add a booking to the profile
- interview_trip(destination, [dates]) — generate pre-search interview questions, skipping what the profile already knows
- search_lounges(airport)
  - Returns lounges with name, terminal, type, accepted access cards, amenities, and opening hours. Type indicates access network: "card" (Priority Pass/LoungeKey), "airline" (frequent flyer status), "bank" (credit card programme), "amex" (Centurion). Annotates results with the user's own lounge cards and frequent flyer status (from preferences) so you can show which lounges they can enter for free.
- optimize_booking(origin, destination, departure_date, [return_date, flex_days, guests, currency, max_results, max_api_calls, need_checked_bag, carry_on_only])
  - Unified trip optimizer: searches alternative origins, destinations, rail+fly stations, hidden-city candidates, and date flexibility. Returns ranked booking strategies with all-in cost (baggage + FF status) and savings vs naive direct booking.
- optimize_trip_dates(origin, destination, from_date, to_date, trip_length, [guests, currency])
  - Find the cheapest dates for a trip within a date range. Uses CalendarGraph API for fast single-request price retrieval across the entire range. Returns optimal departure dates sorted by total cost.
- assess_trip(origin, destination, depart_date, return_date, [guests, passport, currency])
  - Pre-check trip viability before booking. Runs parallel checks for flights, hotels, visa, and weather. Returns GO/WAIT/NO_GO verdict with cost breakdown.
- watch_price(type, origin, destination, date, target_price, [return_date, location, check_in, check_out, currency])
  - Create a price watch. Monitors flight or hotel prices and tracks history. Returns current price vs target.
- list_watches()
  - Show all active price watches with status (watching/triggered/expired) and price history.
- check_watches()
  - Re-check all active watches against current prices. Returns which prices dropped below target.
- provider_health()
  - Show per-provider health summary: total calls, success rate, average latency, last error. Read from ~/.trvl/health.jsonl.
- plan_flight_bundle(origin, destination, departure_date, [return_date])
  - Finds efficient flight package/bundle candidates.
- find_interactive(query, [context])
  - Guided interactive trip finder for under-specified travel searches.

## MCP Prompts

- plan-trip(origin, destination, departure_date, return_date, [budget])
- find-cheapest-dates(origin, destination, month)
- compare-hotels(location, check_in, check_out, [priorities])
- where-should-i-go(origin, [month, budget])
- packing-list(destination, dates, [trip_type, activities])
- setup_profile()
- setup_providers()

## CLI (14 commands)

trvl flights JFK LHR 2026-07-01
trvl flights HEL BCN 2026-07-01 --return 2026-07-08 --cabin business
trvl dates HEL NRT --from 2026-06-01 --to 2026-06-30
trvl hotels "Tokyo" --checkin 2026-06-15 --checkout 2026-06-18 --stars 4
trvl prices "<hotel_id>" --checkin 2026-06-15 --checkout 2026-06-18
trvl explore HEL --format json
trvl grid HEL NRT --depart-from 2026-07-01 --depart-to 2026-07-07 --return-from 2026-07-08 --return-to 2026-07-14
trvl destination "Tokyo" --dates 2026-06-15,2026-06-18
trvl trip-cost HEL BCN --depart 2026-07-01 --return 2026-07-08 --guests 2
trvl weekend HEL --month july-2026 --budget 500
trvl suggest HEL BCN --around 2026-07-15 --flex 7
trvl multi-city HEL --visit BCN,ROM,PAR --dates 2026-07-01,2026-07-21
trvl mcp              # MCP stdio server
trvl mcp --http       # MCP HTTP server

## Detailed docs

- Full README: https://github.com/MikkoParkkola/trvl/blob/main/README.md
- Agent setup: https://github.com/MikkoParkkola/trvl/blob/main/AGENTS.md
- Design doc: https://github.com/MikkoParkkola/trvl/blob/main/docs/DESIGN.md