# trvl

> Google Flights + 5 hotel sources + 20 ground providers from your terminal. Free, no API keys.

trvl is a single Go binary that searches Google Flights, Google Hotels, Trivago, Airbnb, Booking.com, Hostelworld, and 20 ground transport providers by speaking their APIs directly. No scraping, no browser automation, no API keys.

## 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 (61 total)

- 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_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])
  - 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])
- hotel_reviews(hotel_id, [limit, sort])
- hotel_rooms(hotel_name, check_in, check_out, [currency])
- 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