Viajante

Flight and hotel search for the terminal, Python, and AI assistants.

Viajante searches Google Flights, Google Hotels, and Booking.com. Use it to compare flights, find cheaper travel dates, explore destinations, or look up places to stay. It runs on your computer and connects directly to the travel sites; no API keys are required.

You can run a search from the command line, call the Python library, or connect an AI assistant through the Model Context Protocol (MCP). Results include prices, itinerary details, source text, and links where available.

Usage guide · Contributing · Report an issue

Install

Requires Python 3.10 or later.

PyPI:

pip install viajante

npx (needs uv and Python 3.10+ on PATH):

npx -y -p @viajante/mcp viajante airports JFK

No install (same uv + Python 3.10+):

uvx --from viajante viajante airports JFK

Quick start

Search for a one-way flight or a hotel stay:

viajante flights JFK-LHR:2026-11-15 --fetch sweep
viajante hotels London 2026-11-15 2026-11-20 --currency GBP --source google

Use future dates when trying the examples. JFK and LHR are airport codes; viajante airports london lists airports for a city so you can choose one.

These searches use HTTP and do not need a browser. Booking.com and the browser mode for Google Flights require the optional browser setup.

Connect an AI assistant

Viajante provides a local MCP server over stdio. Requires uv and Python 3.10+. Add this entry to your assistant's MCP configuration:

{
  "mcpServers": {
    "viajante": {
      "command": "npx",
      "args": ["-y", "@viajante/mcp"]
    }
  }
}

That entry runs uvx --from viajante[mcp,browser]==<version> viajante-mcp, with <version> pinned to the npm package. search_explore needs the browser extra. Install Chromium once (Playwright's browser cache is shared per user): uvx --from 'viajante[mcp,browser]==<version>' playwright install chromium.

Native Python (no Node):

{
  "mcpServers": {
    "viajante": {
      "command": "uvx",
      "args": ["--from", "viajante[mcp]", "viajante-mcp"]
    }
  }
}

The native configuration supports Google Flights and Google Hotels without Chromium. npx still needs uvx (and Python 3.10+) on PATH. If you use an existing Python environment instead, install pip install 'viajante[mcp]' and configure the client to run that environment's viajante-mcp executable.

For a client that only connects to a URL, run the server on loopback with viajante-mcp --transport streamable-http and point the client at http://127.0.0.1:8000/mcp. This has no authentication; every client shares this machine's IP and the provider cooldown, so do not expose it. Details are in usage.

Once connected, you can ask:

Find a seven-night round trip from BOS to LHR, departing between November 1 and November 30, 2026. Compare the departure dates.

Search for hotels in Tokyo from November 12 to November 16, 2026, for two adults. Use JPY and require free cancellation.

Every tool result (except lookup_airports) carries one envelope: status, completeness, empty_reason (provider_empty / filtered_out / not_loaded), retry_after and observed_at. Only provider_empty means the provider found nothing.

The server exposes twenty-two tools:

Use the command line

Each search command accepts --save FILE to write a JSON report. Run viajante <command> --help for its options.

For example, compare dates for a seven-night round trip:

viajante dates BOS-LHR --from 2026-11-01 --to 2026-11-30 --nights 7

See the usage guide for round trips, flexible dates, filters, hotel searches, and saved reports.

Use Python

get_flights accepts the same route format as the CLI and returns a typed report:

from viajante import get_flights

report = get_flights("JFK-LHR:2026-11-15", fetch="sweep", top=5)

for result in report.queries:
    if result.status == "ok":
        for offer in result.offers:
            print(offer.price, report.currency, offer.airline, offer.duration)
    else:
        print(result.error)

The library also exports FlightQuery, HotelQuery, and the search_* functions. The Python examples show how to build queries directly.

Optional browser support

For Booking.com or Google Flights with --fetch detail, install Playwright and Chromium in the environment that runs Viajante:

pip install 'viajante[browser]'
playwright install chromium

For the uvx MCP configuration, change --from to viajante[mcp,browser] and install Chromium through that same environment:

uvx --from 'viajante[mcp,browser]' playwright install chromium

Flight searches default to --fetch auto: with Playwright installed, they use the browser for one or two queries and HTTP for larger batches. Without Playwright, they use HTTP. Hotel searches default to Booking.com in the CLI and Google Hotels in MCP; use --source google for CLI hotel searches without a browser.

Understanding the results

• Currency: Flight searches use the origin airport's country to choose a currency when possible. You can set one explicitly with --currency. Standalone hotel searches require a currency. Viajante does not convert between currencies.
• Baggage: Use --bags or --carry-on to request baggage pricing from Google Flights. An optional --baggage-buffer affects ranking; it is a user-supplied amount, not a quoted bag fee, and defaults to zero.
• Hotels: Prices cover the requested stay. Free cancellation is required by default, but an applied search filter and a property's stated terms are recorded separately. Google ratings use a 0–5 scale; Booking.com uses 0–10.
• Recommendation: A successful flights query may carry a recommendation block (none when the provider returned nothing): a pick that respects the requirements you named (and reports any it had to relax), plus up to three genuinely different options with factual highlights and tradeoffs. The score weights are published, unknown fields are labelled unknown, and prices in different currencies are never compared. It adds to the offer list; it does not replace it.
• Price comparisons: When present, typical is a median from the same route's date calendar. It is not a historical market average.
• Trip totals: A combined total is shown only when both searches return usable prices, their dates overlap, and their currencies match. It adds the flight fare and hotel stay; it does not create a package booking.
• Missing information: Fields that cannot be determined remain unknown or are omitted. Source text is retained with offers to help you inspect the result.

Travel sites can change their pages, block requests, or return incomplete results. Prices and availability can also change after a search. Check the final fare, baggage allowance, hotel total, and cancellation terms on the provider's site before booking.

Contributing

Bug reports, documentation improvements, and code contributions are welcome. The contributor guide covers local setup and the offline test suite. For a bug report, include your version, command, and error message, with personal information removed.

License

Viajante is available under the MIT License. It is an independent project and is not affiliated with Google, Booking.com, or any airline. Use of those services is subject to their respective terms: Google and Booking.com.