# Google Flights MCP

[![CI](https://github.com/pisanuw/claude-google-flights-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pisanuw/claude-google-flights-mcp/actions/workflows/ci.yml)

An [MCP](https://modelcontextprotocol.io) server that lets Claude search Google
Flights and track fares over time. Google has no official flights API, so this
server calls [SerpAPI](https://serpapi.com/google-flights-api)'s `google_flights`
engine, which runs the search server-side and returns structured JSON.

## Tools

| Tool | What it does |
|---|---|
| `search_flights` | Search between two airports (one-way or round-trip), with cabin class, passengers, stops, and price filters. |
| `search_multi_city` | Search a multi-city itinerary (2+ legs). Returns leg-1 options; advance leg by leg with `get_return_flights`. |
| `get_return_flights` | Select a flight via its `departure_token` to see the next set of options (round-trip return, or next multi-city leg). |
| `get_booking_options` | For a chosen flight (via its `booking_token`), list where to book and the price at each provider. |
| `track_price` | Save a search as a price watch, with an optional target price and label. |
| `list_price_watches` | List all watches and their most recent recorded price. |
| `check_prices` | Re-check every watch now, record prices, and report drops / target hits. |
| `get_price_history` | Show the recorded price history for a watch. |
| `untrack_price` | Delete a watch and its history. |

### Cabin class

`search_flights`, `search_multi_city`, and `track_price` all accept
`travel_class`: **economy** (default), **premium_economy**, **business**,
**first**. Just ask, e.g. *"business class SEA to London."*

## Setup

1. **Get a SerpAPI key** (free tier: 100 searches/month) at
   <https://serpapi.com/manage-api-key>.

2. **Add the key:**

   ```bash
   cp .env.example .env      # then edit .env and set SERPAPI_API_KEY=...
   ```

3. **Install dependencies** (uv provisions an isolated Python ≥3.10):

   ```bash
   uv sync
   ```

4. **Register with Claude Code** (user scope = available in every session):

   ```bash
   claude mcp add google-flights -s user -- \
     uv run --directory /Users/pisan/bitbucket/pisanuw/google-flights python server.py
   ```

   Restart Claude Code (or run `/mcp`) to pick up the tools.

## Example prompts

- "Nonstop round-trip SEA→NRT, Oct 3 back Oct 17, under $1200."
- "Business class one-way SEA to LHR on Nov 15."
- "Multi-city: SEA→NRT Oct 3, NRT→ICN Oct 10, ICN→SEA Oct 17."
- "Track SEA→LAX Nov 15–20 and alert me if it drops below $120."
- "Check my flight watches" / "show the price history for watch 2."

## Price alerts (background checking)

`check_prices` runs on demand (when you ask Claude). For hands-off alerts, run
the standalone checker on a schedule; it records prices and fires a native macOS
notification on any drop or target hit:

```bash
uv run python check_watches.py
```

Schedule it with launchd or cron (e.g. hourly). Watches and history are stored
in `watches.db` (gitignored) next to the server, so the scheduled checker and
the MCP tools share the same data.

## Notes

- Airports are IATA codes (`SEA`, `NRT`, `LHR`). Multiple origins can be
  comma-separated (`SEA,PDX`).
- For round trips, each result's `price` is the total round-trip fare.
- Multi-city is leg-by-leg: the first response is leg-1 options; the shown price
  is the full-itinerary estimate. Use `get_return_flights` with a
  `departure_token` to advance.
- `deep_search=true` matches google.com/travel/flights more closely but is slower.
- Every search (including each watch re-check) counts against your SerpAPI quota.