google-flights-mcp

# Google Flights MCP: real-time fares your agent can search across a whole date range, ad-free

**Sign in with Google, nothing to paste into your client:**

```bash
claude mcp add --transport http google-flights https://flights.flightpowers.com/mcp/oauth
```

Works in clients that support MCP authorization: a Sign in button appears, you sign in with
Google, and you paste your RapidAPI key once on the `/connect` page. Nothing goes in your client
config.

**Or bring your own RapidAPI key:**

```bash
claude mcp add --transport http google-flights https://google-flights-mcp.flightpowers.com/mcp --header "x-rapidapi-key: YOUR_RAPIDAPI_KEY"
```

Hosted. Nothing to clone, nothing to build. Listed in the official MCP Registry as
`com.flightpowers/google-flights-mcp`. Health check:
[`/health`](https://google-flights-mcp.flightpowers.com/health).

**Need a key?** Subscribe to the Google Flights Live API on RapidAPI, free tier available,
and copy your `x-rapidapi-key`: **https://rapidapi.com/mtnrabi/api/google-flights-live-api**

**No key yet? Start with the free server, same search, no signup:**
`claude mcp add --transport http google-flights-free https://google-flights-lulu.flightpowers.com/mcp`
(ad-supported: one disclosed sponsored card per result, fan-out capped at 15, and clients that
cannot render the sponsored card may be capped further.) Come back here when the ads, the
15-search cap, or those client restrictions get in your way.

---

## Cursor Marketplace

Once listed, install directly from the [Cursor Marketplace](https://cursor.com/marketplace). Until
then, add the remote MCP server manually:

```bash
# In Cursor, add via Settings → MCP Servers → Add Server
# URL: https://google-flights-mcp.flightpowers.com/mcp
# Header: x-rapidapi-key: YOUR_RAPIDAPI_KEY
```

Or use the `mcp.json` at the root of this repo, which references `${RAPIDAPI_KEY}` as a plugin
variable.

## What your agent gets

Two tools that answer a *fare question*, not a *date lookup*.

- **Ask open-ended questions.** "Cheapest one-way to Sri Lanka anywhere in October", "5 to 7
  nights in Rome sometime in May, from Tel Aviv or Larnaca": each is **one** tool call. Both
  tools take a departure date **range**, a **list** of destination airports, and (round-trip) a
  `nights` value instead of a fixed return date, and expand them internally.
- **Say whether a price is actually good.** Every result carries Google's own historical range
  for that route and period: `price_insights_low`, `price_insights_high`, and a
  `price_range_in_relation_to_other_periods` verdict of `low` / `typical` / `high`. That is what
  lets an agent answer "$209 is typical here, don't rush" instead of just quoting a number.
- **Book, not just browse.** Every result includes a `buy_link` to Google Flights.
- **Know what it spent.** Every response carries `api_usage`: requests used by this call, and
  what is left on the caller's plan. See [Spend reporting](#spend-reporting-api_usage).
- **Know what it searched.** Every response carries `search_coverage`, so the model can say
  honestly which dates and destinations the answer is based on.

Results are live fares. **They go stale within minutes: never cache a fare or reuse an earlier
result; search again and state when the data was fetched.**

## Get a key (free tier available)

The server holds no upstream credential of its own. Every search is billed to *your* RapidAPI
subscription, which is why the key travels with the request.

1. Subscribe to the Google Flights Live API:
   **https://rapidapi.com/mtnrabi/api/google-flights-live-api**
2. Copy your `x-rapidapi-key`.
3. Pass it to the server in any one of the three ways below.

If a key is missing, the tools do not fail silently and do not spend anything. They return
`needs_api_key: true` with the signup URL and these instructions, phrased for the model to read
back to you.

## Three ways to pass your key

| Way | How | When to use it |
|---|---|---|
| **Header** (preferred) | `--header "x-rapidapi-key: YOUR_RAPIDAPI_KEY"` | Anything that lets you set headers. Keys stay out of URLs, and therefore out of proxy and access logs. |
| **Query parameter** | `https://google-flights-mcp.flightpowers.com/mcp?rapidapi_key=YOUR_RAPIDAPI_KEY` | Hosts that only let you paste a URL: claude.ai's custom-connector dialog is the case that matters. |
| **Client API-key field** | Paste the key into the client's own "API key" box | Hosts that send `authorization: Bearer <key>` or `x-api-key`. Smithery's saved-config form (`config.rapidApiKey=`) is also accepted. |

First non-empty source wins, in that order. The key is never logged, never echoed into an error
message, and never returned in a tool response.

## Gemini CLI

Install via the Gemini extensions CLI:

```bash
gemini extensions install https://github.com/mtnrabi/google-flights-mcp
```

The installer will prompt for your RapidAPI key. Subscribe at
https://rapidapi.com/mtnrabi/api/google-flights-live-api (free tier available) and copy your
`x-rapidapi-key`.

## A fourth way: sign in once at `/connect`

This is the page the sign-in URL at the top of this README sends you to. A client that speaks MCP
authorization walks you through it on its own; the steps below are the same thing done by hand.

Where a deployment has it enabled (check `connect_enabled` on `/health`), there is a page at
`/connect` that replaces all of the above with a sign-in:

1. Open **https://google-flights-mcp.flightpowers.com/connect** (hotels:
   **https://hotels.flightpowers.com/connect**) and sign in with Google.
2. Paste your RapidAPI key once, into a form, over TLS.
3. Copy the connect URL it gives you back, `…/mcp?fp_token=fpk_…`, and use that as the server
   URL in your MCP client. Clients that let you set headers can send the same token as
   `Authorization: Bearer fpk_…` instead.

What that buys you: your RapidAPI key is not in your client config, not in a URL, and not in
whatever logs that URL passes through. What it costs: the server stores your key, encrypted, and
knows your Google account id and email address. `Disconnect` on the same page deletes the record
and kills every connect token for your account, immediately. The full description is
[section 2a of the privacy policy](https://google-flights-mcp.flightpowers.com/privacy).

Some details worth knowing:

- **Saving runs one check.** The key is validated against the listing before it is stored, so a
  typo fails on the page rather than in your client an hour later. That check costs **at most one
  request** from your own plan: on the free BASIC plan (10 a month), one of ten. A key that
  RapidAPI rejects at the gateway costs nothing.
- **A key on the request always wins.** If you send an `x-rapidapi-key` header (or any of the
  other channels above) *and* carry a connect token, the request's own key is used. Nothing you
  already have set up changes behaviour because you signed in.
- **The token is not your key** and cannot be turned back into it. It is valid for 90 days, and
  it stops resolving the moment you disconnect. A call carrying a token whose key has been
  disconnected gets a `needs_api_key` reply telling you to reconnect. It never falls back to
  somebody else's subscription and never spends anything.
- **BASIC is free.** [Google Flights Live API](https://rapidapi.com/mtnrabi/api/google-flights-live-api)
  · [Booking Live API](https://rapidapi.com/mtnrabi/api/booking-live-api). One RapidAPI key covers
  whichever of the two you have subscribed to; you connect it once.

### Running `/connect` on your own deployment

Off unless **all four** of these are set. A half-configured deployment registers none of the
routes and serves keyed callers exactly as before; `/health` reports `connect_enabled` so that is
visible rather than guessed.

| Variable | What it is |
|---|---|
| `GOOGLE_OAUTH_CLIENT_ID` | Google Cloud Console → Credentials → OAuth client ID, type **Web application**. Ends `.apps.googleusercontent.com`. |
| `GOOGLE_OAUTH_CLIENT_SECRET` | The same client's secret (`GOCSPX-…`). |
| `MCP_KEY_MASTER` | 32 bytes, base64: `openssl rand -base64 32`. Encrypts stored keys (AES-256-GCM) and derives the cookie and token signing keys. |
| `DATABASE_URL` | Neon Postgres, **pooled** endpoint (`…-pooler…`). Schema: `migrations/001_mcp_user_keys.sql`. |

Optional: `MCP_CONNECT_VALIDATE=0` stores a pasted key without checking it first.

**Authorised redirect URIs to register on the Google client**, one per product origin, exactly:

```
https://google-flights-mcp.flightpowers.com/connect/callback
https://hotels.flightpowers.com/connect/callback
```

`flights.flightpowers.com` needs **no** entry. `/connect` and `/connect/start` bounce an alias to
the canonical origin before the sign-in starts, because cookies are per-host and Google compares
`redirect_uri` literally: an alias that started its own sign-in would come back to a host with no
state cookie and fail with a message that reads like a Google misconfiguration.

Also on the OAuth consent screen: scopes `openid` and `.../auth/userinfo.email`, and nothing else.

**Rotating `MCP_KEY_MASTER` logs everybody out and invalidates every stored key.** That is
deliberate: after a rotation nothing is left holding a token that resolves to a key nobody can
read. Users see "connect again", not a failed search. `key_version` on the table is there so a
staged rotation is possible later without a flag day.

### Verifying the flow end to end

Migration first, once per database:

```bash
psql "$DATABASE_URL" -f migrations/001_mcp_user_keys.sql
```

Then, after deploying:

```bash
# 1. The feature is actually on.
curl -s https://google-flights-mcp.flightpowers.com/health | grep connect_enabled

# 2. The page renders for an anonymous visitor.
curl -sI https://google-flights-mcp.flightpowers.com/connect        # 200
curl -sI https://google-flights-mcp.flightpowers.com/connect/start  # 302 to accounts.google.com

# 3. Sign in in a browser, paste a key, copy the connect U