{
  "markdown": "# Viajante\n\nFlight and hotel search for the terminal, Python, and AI assistants.\n\n[![PyPI](https://img.shields.io/pypi/v/viajante.svg)](https://pypi.org/project/viajante/)\n[![npm](https://img.shields.io/npm/v/@viajante/mcp.svg)](https://www.npmjs.com/package/@viajante/mcp)\n[![Tests](https://github.com/felipebasurto/viajante/actions/workflows/test.yml/badge.svg)](https://github.com/felipebasurto/viajante/actions/workflows/test.yml)\n\nViajante searches Google Flights, Google Hotels, and Booking.com. Use it to\ncompare flights, find cheaper travel dates, explore destinations, or look up\nplaces to stay. It runs on your computer and connects directly to the travel\nsites; no API keys are required.\n\nYou can run a search from the command line, call the Python library, or connect\nan AI assistant through the Model Context Protocol (MCP). Results include\nprices, itinerary details, source text, and links where available.\n\n[Usage guide](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md)\n· [Contributing](https://github.com/felipebasurto/viajante/blob/main/CONTRIBUTING.md)\n· [Report an issue](https://github.com/felipebasurto/viajante/issues)\n\n## Install\n\nRequires **Python 3.10 or later**.\n\nPyPI:\n\n```bash\npip install viajante\n```\n\nnpx (needs [`uv`](https://docs.astral.sh/uv/) and Python 3.10+ on PATH):\n\n```bash\nnpx -y -p @viajante/mcp viajante airports JFK\n```\n\nNo install (same `uv` + Python 3.10+):\n\n```bash\nuvx --from viajante viajante airports JFK\n```\n\n## Quick start\n\nSearch for a one-way flight or a hotel stay:\n\n```bash\nviajante flights JFK-LHR:2026-11-15 --fetch sweep\nviajante hotels London 2026-11-15 2026-11-20 --currency GBP --source google\n```\n\nUse future dates when trying the examples. `JFK` and `LHR` are airport codes;\n`viajante airports london` lists airports for a city so you can choose one.\n\nThese searches use HTTP and do not need a browser. Booking.com and the browser\nmode for Google Flights require the optional\n[browser setup](#optional-browser-support).\n\n## Connect an AI assistant\n\nViajante provides a local MCP server over stdio. Requires\n[`uv`](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+.\nAdd this entry to your assistant's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"viajante\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@viajante/mcp\"]\n    }\n  }\n}\n```\n\nNative Python (no Node):\n\n```json\n{\n  \"mcpServers\": {\n    \"viajante\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"viajante[mcp]\", \"viajante-mcp\"]\n    }\n  }\n}\n```\n\nThis configuration supports Google Flights and Google Hotels without Chromium.\nnpx still needs `uvx` (and Python 3.10+) on PATH. If you use an existing\nPython environment instead, install `pip install 'viajante[mcp]'` and configure\nthe client to run that environment's `viajante-mcp` executable.\n\nOnce connected, you can ask:\n\n> Find a seven-night round trip from BOS to LHR, departing between November 1\n> and November 30, 2026. Compare the departure dates.\n\n> Search for hotels in Tokyo from November 12 to November 16, 2026, for two\n> adults. Use JPY and require free cancellation.\n\nThe server exposes seven tools:\n\n| Tool | Use it to |\n| --- | --- |\n| `search_flights` | Search one-way, round-trip, or multi-city flights. |\n| `search_dates` | Compare the cheapest returned fare for each departure date in a window. |\n| `search_flex` | Check dates around a target departure, then fetch flights for the cheapest day. |\n| `search_explore` | Discover destinations from an origin airport and price a shortlist. |\n| `search_hotels` | Find stays with total-stay prices and cancellation details where available. |\n| `search_trip` | Search flights and hotels together and sum compatible results. |\n| `lookup_airports` | Look up airport codes offline. |\n\n## Use the command line\n\nEach search command accepts `--save FILE` to write a JSON report. Run\n`viajante <command> --help` for its options.\n\n| Command | Purpose |\n| --- | --- |\n| `viajante flights` | Search specific routes and dates. |\n| `viajante dates` | Compare departure dates across a window of up to 31 days. |\n| `viajante flex` | Search a few days either side of a target date. |\n| `viajante explore` | Find destinations from an origin airport. |\n| `viajante hotels` | Search Google Hotels or Booking.com. |\n| `viajante trip` | Search flights and a hotel stay in one request. |\n| `viajante airports` | Find airport codes by city or code. |\n\nFor example, compare dates for a seven-night round trip:\n\n```bash\nviajante dates BOS-LHR --from 2026-11-01 --to 2026-11-30 --nights 7\n```\n\nSee the [usage guide](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md)\nfor round trips, flexible dates, filters, hotel searches, and saved reports.\n\n## Use Python\n\n`get_flights` accepts the same route format as the CLI and returns a typed\nreport:\n\n```python\nfrom viajante import get_flights\n\nreport = get_flights(\"JFK-LHR:2026-11-15\", fetch=\"sweep\", top=5)\n\nfor result in report.queries:\n    if result.status == \"ok\":\n        for offer in result.offers:\n            print(offer.price, report.currency, offer.airline, offer.duration)\n    else:\n        print(result.error)\n```\n\nThe library also exports `FlightQuery`, `HotelQuery`, and the `search_*`\nfunctions. The\n[Python examples](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md#python-library)\nshow how to build queries directly.\n\n## Optional browser support\n\nFor Booking.com or Google Flights with `--fetch detail`, install Playwright\nand Chromium in the environment that runs Viajante:\n\n```bash\npip install 'viajante[browser]'\nplaywright install chromium\n```\n\nFor the `uvx` MCP configuration, change `--from` to `viajante[mcp,browser]` and\ninstall Chromium through that same environment:\n\n```bash\nuvx --from 'viajante[mcp,browser]' playwright install chromium\n```\n\nFlight searches default to `--fetch auto`: with Playwright installed, they use\nthe browser for one or two queries and HTTP for larger batches. Without\nPlaywright, they use HTTP. Hotel searches default to Booking.com in the CLI\nand Google Hotels in MCP; use `--source google` for CLI hotel searches without\na browser.\n\n## Understanding the results\n\n- **Currency:** Flight searches use the origin airport's country to choose a\n  currency when possible. You can set one explicitly with `--currency`.\n  Standalone hotel searches require a currency. Viajante does not convert\n  between currencies.\n- **Baggage:** Use `--bags` or `--carry-on` to request baggage pricing from\n  Google Flights. An optional `--baggage-buffer` affects ranking; it is a\n  user-supplied amount, not a quoted bag fee, and defaults to zero.\n- **Hotels:** Prices cover the requested stay. Free cancellation is required\n  by default, but an applied search filter and a property's stated terms are\n  recorded separately. Google ratings use a 0–5 scale; Booking.com uses 0–10.\n- **Price comparisons:** When present, `typical` is a median from the same\n  route's date calendar. It is not a historical market average.\n- **Trip totals:** A combined total is shown only when both searches return\n  usable prices, their dates overlap, and their currencies match. It adds the\n  flight fare and hotel stay; it does not create a package booking.\n- **Missing information:** Fields that cannot be determined remain unknown\n  or are omitted. Source text is retained with offers to help you inspect\n  the result.\n\nTravel sites can change their pages, block requests, or return incomplete\nresults. Prices and availability can also change after a search. Check the\nfinal fare, baggage allowance, hotel total, and cancellation terms on the\nprovider's site before booking.\n\n## Contributing\n\nBug reports, documentation improvements, and code contributions are welcome.\nThe [contributor guide](https://github.com/felipebasurto/viajante/blob/main/CONTRIBUTING.md)\ncovers local setup and the offline test suite. For a bug report, include your\nversion, command, and error message, with personal information removed.\n\n## License\n\nViajante is available under the\n[MIT License](https://github.com/felipebasurto/viajante/blob/main/LICENSE).\nIt is an independent project and is not affiliated with Google, Booking.com,\nor any airline. Use of those services is subject to their respective terms:\n[Google](https://policies.google.com/terms) and\n[Booking.com](https://www.booking.com/content/terms.html).\n\n<!-- mcp-name: io.github.felipebasurto/viajante -->\n",
  "bytes": 8407,
  "sha": "4cdb719a96aba6743beec5ea0152397c8184319cd8c998a5d30877dc48731f7b",
  "repo_slug": "felipebasurto/viajante",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_felipebasurto_viajante_e64b5cd4/readme"
}