ghotels

ghotels is a ground-up, actively maintained rebuild of him229/stays, which pioneered this approach but is no longer maintained — see Acknowledgements.

Why ghotels?

Related MCP server: stays

Quick start

# 1. Install (pipx keeps it isolated and on your PATH)
pipx install ghotels

# 2. Register the MCP server with your client
ghotels setup claude        # Claude Code / Claude Desktop
ghotels setup codex         # OpenAI Codex CLI
ghotels setup chatgpt       # prints remote-connector instructions

# 3. Restart your client, then ask:

"Find me a 4-star hotel in Tokyo for Sep 22–26 under $150 a night."

"Compare rooms, rates, and cancellation for the top 5 hotels near the Louvre."

"Show me pet-friendly refundable stays in Austin next weekend."

Prefer the terminal? The CLI speaks the same engine:

ghotels "tokyo hotels" --check-in 2026-09-22 --check-out 2026-09-26 --stars 4 --price-max 150

How it works

Every surface funnels through one typed core: validated filters are encoded by a documented slot map into the f.req envelope, posted through a Chrome-impersonated, token-bucket-paced transport, and the response frames are walked back into frozen pydantic models. Cancellation deadlines are anchored to your check-in date — parsing never reads the wall clock, so results are reproducible.

MCP tools

All three return one canonical envelope (ok, kind, query, count, results), and bad arguments come back as corrective error messages that list the valid options — the calling model can fix itself without a retry loop. The server also ships two prompts (choosing-a-tool, compare-hotels-in-city) and a live config resource at resource://google-hotels-mcp/configuration.

Everything search_hotels takes (dates required), plus:

CLI

ghotels routes a bare query straight to search — ghotels "paris hotels" just works. Subcommands:

# Filters compose; enums are case-insensitive
ghotels search "london hotels" \
    --check-in 2026-09-22 --check-out 2026-09-26 \
    --stars 4 --stars 5 --amenity POOL --brand HILTON \
    --price-max 300 --sort-by LOWEST_PRICE

# Machine-readable output
ghotels "rome hotels" --format json     # one envelope
ghotels "rome hotels" --format jsonl    # one record per line

Python API

Async-first, with a synchronous facade that reuses one HTTP session:

import asyncio
from datetime import date

from ghotels import AsyncGoogleHotels, Location, SearchFilters, SortBy, StayDates


async def main() -> None:
    async with AsyncGoogleHotels() as api:
        hotels = await api.search(
            SearchFilters(
                location=Location(query="tokyo hotels"),
                dates=StayDates(check_in=date(2026, 9, 22), check_out=date(2026, 9, 26)),
                star_classes=[4, 5],
                sort_by=SortBy.LOWEST_PRICE,
            )
        )
        best = hotels[0]
        print(best.name, best.price and best.price.amount)

        detail = await api.details(
            best.entity_key,
            dates=StayDates(
                check_in=date(2026, 9, 22),
                check_out=date(2026, 9, 26),
            ),
        )
        for room in detail.rooms:
            for rate in room.rates:
                print(rate.provider, rate.price, rate.cancellation.kind.value)


asyncio.run(main())

# Synchronous — same API, no event loop to manage
from ghotels import GoogleHotels, Location, SearchFilters

with GoogleHotels() as api:
    for hotel in api.search(SearchFilters(location=Location(query="berlin hotels")))[:5]:
        print(hotel.name, hotel.rating and hotel.rating.score)

search_with_details fans out detail lookups concurrently and reports per-hotel failures with a retryable flag instead of aborting the batch. Everything public is exported from the top-level ghotels package and fully typed (py.typed).

Configuration

All knobs are environment variables:

Docker

# Published multi-arch image (amd64 + arm64)
docker run --rm -p 8000:8000 ghcr.io/alexechoi/google-hotels-mcp:latest

# Or with compose
docker compose --profile prod up      # published image + healthcheck
docker compose --profile dev up --build

The container serves streamable-HTTP MCP on :8000. A bare GET /mcp returns 405/406 by design — the transport requires Accept: application/json, text/event-stream.

Development

git clone https://github.com/alexechoi/google-hotels-mcp.git
cd google-hotels-mcp
make install-dev    # uv sync --extra dev
make check          # ruff format --check + ruff check + mypy --strict + pytest
make test-live      # end-to-end against the real endpoint (network)

The offline suite (180+ tests) runs against live-captured fixtures and includes byte-parity goldens for the request encoder. Wire-format details live in docs/PROTOCOL.md. See CONTRIBUTING.md for the dev loop and PR conventions.

Acknowledgements

ghotels exists because of two projects:

• stays by Himank Yadav did the original reverse engineering of the Google Hotels batchexecute RPC and proved this approach end to end. It is, at the time of writing, no longer maintained — the last activity was April 2026 and community fix PRs have gone unreviewed since — which is the direct reason this project exists. ghotels is a fresh, independently written implementation (not a fork) that re-derives the protocol from stays' documented findings, folds in the fixes that upstream never merged, and stays under active maintenance.

• fli by Punit Arani pioneered the direct-batchexecute technique for Google Flights that inspired stays in the first place.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Google. It uses an unofficial, undocumented interface that may change or break at any time; use it responsibly and respect Google's terms of service and rate limits (the built-in limiter defaults to 10 requests/second).

License

MIT © Alex Choi