# Google Flights MCP

An [MCP](https://modelcontextprotocol.io) server that lets Claude, ChatGPT and any other MCP client
search **Google Flights**: prices, stops, durations, cheapest day in a range, nearby-airport comparison
and a deep link to book.

> Not affiliated with or endorsed by Google. See [Legal](#legal-and-fair-use) before using it.

## Tools

| Tool | What it does |
|---|---|
| `search_flights` | One-way or round-trip search for a date: passengers, cabin, max stops, sorting |
| `find_cheapest_dates` | Cheapest day in a date range (optionally for a fixed trip length) |
| `compare_airports` | Cheapest fare across several origin/destination airports (e.g. MXP/LIN/BGY → LHR/LGW) |
| `find_airport` | Offline lookup of IATA codes from a city or airport name |
| `check_for_updates` | Tells the assistant whether a newer version is on GitHub (called once per conversation) |

Every search result includes a `google_flights_url` so you can verify and book.

## Install

You only need [uv](https://docs.astral.sh/uv/getting-started/installation/) (it fetches Python and the
dependencies for you). Nothing to clone or build.

**Do this once first (warm-up).** The very first run downloads and builds everything (about a minute), which is
longer than the start-up timeout of most clients, so the first launch from Claude would appear to fail.
Pre-download it in a terminal, then register it:

```bash
uvx --from git+https://github.com/marcopa84/GoogleFlightsMCP google-flights-mcp --version
```

After that, starting takes ~2 seconds.

### Let Claude install it for you

Paste this into Claude Code (or Claude Desktop with file access) and it will do the setup, asking before
it touches any config:

```text
Install this MCP server for me and check it works: https://github.com/marcopa84/GoogleFlightsMCP
Follow INSTALL_FOR_AI.md in that repo.
```

If you cloned the repo and open Claude Code in it, you also get three slash commands:
`/install` (set up), `/doctor` (diagnose problems), `/flights <request>` (search in plain language).

Or do it by hand:

### Claude Code

```bash
claude mcp add google-flights -- uvx --from git+https://github.com/marcopa84/GoogleFlightsMCP google-flights-mcp
```

### Claude Desktop

Settings → Developer → Edit Config, then add:

```json
{
  "mcpServers": {
    "google-flights": {
      "command": "/usr/local/bin/uvx",
      "args": ["--from", "git+https://github.com/marcopa84/GoogleFlightsMCP", "google-flights-mcp"]
    }
  }
}
```

Replace `/usr/local/bin/uvx` with the output of `which uvx` (Claude Desktop does not see your shell PATH).
Keep any other keys already in the file.

Then **quit Claude Desktop completely** (⌘Q on macOS, tray icon → Quit on Windows; closing the window is not
enough), reopen it, start a new chat and ask: *"Find me the cheapest flights from Milan to London next month,
nonstop only."* If the tools do not appear, check `~/Library/Logs/Claude/mcp-server-google-flights.log`.

### ChatGPT (and other remote clients)

ChatGPT connects to servers on the public internet, so run the HTTP transport and expose it with a tunnel.
You need a ChatGPT plan with custom connectors / Developer Mode (check OpenAI's current docs for eligibility).

```bash
# terminal 1
uvx --from git+https://github.com/marcopa84/GoogleFlightsMCP google-flights-mcp --transport http --port 8000 --allow-any-host
# terminal 2 (any tunnel works; this one needs no account)
cloudflared tunnel --url http://localhost:8000
```

In ChatGPT: Settings → Connectors → Advanced → Developer mode → add a connector with
`https://<your-tunnel>.trycloudflare.com/mcp`, authentication *none*.

⚠️ This server has no authentication. Anyone who learns your tunnel URL can make your machine search
Google Flights. Stop the tunnel when you are done, and do not leave it running unattended.
Prefer `--public-host <your-tunnel-hostname>` over `--allow-any-host` if the hostname is stable.

### From a clone

```bash
git clone https://github.com/marcopa84/GoogleFlightsMCP && cd GoogleFlightsMCP
uv sync
uv run google-flights-mcp          # stdio
uv run pytest                      # tests (offline)
uv run pytest -m live              # real Google Flights check
```

## Configuration (environment variables, all optional)

| Variable | Default | Meaning |
|---|---|---|
| `GFLIGHTS_BACKEND` | `auto` | `google`, `serpapi`, or `auto` (Google first, SerpAPI as fallback when a key is set) |
| `SERPAPI_API_KEY` | – | Enables the [SerpAPI](https://serpapi.com) `google_flights` backend: a paid/free-tier API, more robust than scraping |
| `GFLIGHTS_CACHE_TTL` | `900` | Seconds identical searches are cached |
| `GFLIGHTS_MIN_INTERVAL` | `1.5` | Minimum seconds between upstream requests |
| `GFLIGHTS_MAX_SCAN` | `14` | Max days a single `find_cheapest_dates` call may scan |
| `GFLIGHTS_PROXY` | – | HTTP(S) proxy for the Google backend |
| `GFLIGHTS_CONSENT_COOKIE` | built-in | See below |
| `GFLIGHTS_UPDATE_CHECK` | `1` | `0` disables the GitHub update check |

In Claude Desktop pass them with an `"env": { ... }` block next to `command`/`args`.

### Cookie consent (EU)

From the EU, Google answers automated requests with a cookie-consent page instead of results. The Google
backend therefore sends the same `SOCS` cookie a browser stores after clicking *Accept all*. That is a
choice made on your behalf: set `GFLIGHTS_CONSENT_COOKIE` to your own value (copy the `SOCS` cookie from
your browser) or to an empty string to send nothing (searches from the EU will then fail).

## Updates

Installed with `uvx --from git+...`, the server picks up the latest commit **every time it starts**. So to
update, just quit the client completely and reopen it (Claude Desktop: ⌘Q / tray → Quit). While the app stays
open the old version keeps running; the assistant calls `check_for_updates` once per conversation and tells you
when a restart would bring in a newer version.

## How it works

```
MCP client ──► tools (server.py) ──► FlightService (cache, rate limit, validation, fallback)
                                         ├─ GoogleFlightsBackend  (fast-flights: Google's public web page)
                                         └─ SerpApiBackend        (official paid API, optional)
```

There is no official Google Flights API. The default backend reads the public page like a browser and can
break when Google changes it; the weekly CI job runs a live canary so you find out quickly. If it breaks,
update first (`uvx --refresh ...`) and open an issue.

## Legal and fair use

This is not legal advice. Points to be aware of:

- Google's Terms of Service restrict automated access. Scraping can violate them even for public pages.
- In the EU, a site operator may contractually forbid scraping of databases that are not otherwise protected
  (CJEU, *Ryanair v PR Aviation*).
- The project is meant for **personal, low-volume use**: it caches, rate-limits and caps range scans.
  Do not host it as a public service, resell the data, or raise the limits to bulk-harvest prices.
- For anything commercial use the `serpapi` backend or a licensed flight-data provider.
- Prices are indicative; always confirm on the booking site.

## Contributing

`INSTALL_FOR_AI.md` is written for AI assistants; keep it in sync when install steps change.

PRs welcome — especially new backends (implement `Backend.search` in `src/google_flights_mcp/backends/`).

## License

MIT