Content
# google-flights-mcp
[](https://www.npmjs.com/package/google-flights-mcp)
[](https://github.com/andreacappelletti97/google-flights-mcp/actions)
[](https://opensource.org/licenses/ISC)
The most feature-rich MCP server for Google Flights. No API key required.
12 tools for searching flights, tracking prices, comparing cabins, analyzing layovers, and more, all powered by real-time Google Flights data.
Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.
## Features no other Google Flights MCP has
- **Carbon emissions** per flight and per leg (CO2 in kg)
- **Price context**: Google's own assessment of whether a price is low, typical, or high
- **Price tracking**: track prices over time with SQLite persistence, detect drops and trends
- **Calendar heatmap**: 60 days of daily prices in a single API call
- **Cabin class comparison**: economy vs premium vs business vs first, side by side
- **Nearby airport suggestions**: find cheaper alternatives (e.g., EWR/LGA near JFK)
- **Layover analysis**: connection time risk assessment (tight/comfortable/overnight)
- **Aircraft & seat details**: Boeing 787 vs 777, seat pitch in inches
- **Google Flights URLs**: direct booking links users can click
## What you can ask
- *"Find nonstop flights from JFK to London next month"*
- *"What's the cheapest week to fly SFO to Tokyo?"*
- *"Compare economy vs business class for LAX to Paris"*
- *"Are there cheaper airports near JFK I should check?"*
- *"Track the price of SFO to NRT on June 15 and alert me if it drops"*
- *"Show me the emissions for flights from SFO to Tokyo"*
- *"Analyze the layovers for connecting flights from SFO to Bangkok"*
## Quick start
### Option 1: npx (no install)
Works immediately with Claude Code:
```bash
claude mcp add google-flights -- npx -y google-flights-mcp
```
Or with Claude Desktop, add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"google-flights": {
"command": "npx",
"args": ["-y", "google-flights-mcp"]
}
}
}
```
### Option 2: Install from source
```bash
git clone https://github.com/andreacappelletti97/google-flights-mcp.git
cd google-flights-mcp
npm install
npm run build
```
Then connect to Claude Code:
```bash
claude mcp add google-flights node /absolute/path/to/google-flights-mcp/dist/index.js
```
Or Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"google-flights": {
"command": "node",
"args": ["/absolute/path/to/google-flights-mcp/dist/index.js"]
}
}
}
```
Restart your MCP client. You should see 12 flight tools available.
## Tools (12)
### Search
| Tool | Description |
|------|-------------|
| `search_flights` | One-way & round-trip search. Returns prices, airlines, durations, stops, aircraft, seat pitch, CO2 emissions, and price context. |
| `search_multi_city` | Multi-leg itinerary search (2-5 segments). |
### Price intelligence
| Tool | Description |
|------|-------------|
| `get_calendar_heatmap` | Full calendar of daily prices (~60 days) from a single API call. Cheapest dates at a glance. |
| `get_price_insights` | Scan a date range to find cheapest departure dates (multiple API calls for precision). |
| `compare_cabin_classes` | Compare economy, premium economy, business, and first class prices for the same route. |
| `track_price` | Record current price and report trend (dropping/rising/stable). Persists in SQLite. |
| `get_price_history` | View all recorded price observations for a tracked route. |
| `list_tracked_routes` | List all routes being price-tracked with last known price. |
### Airport tools
| Tool | Description |
|------|-------------|
| `lookup_airport` | Search 8,800+ airports by city, name, IATA code, or country. |
| `find_nearby_airports` | Find alternative airports within a radius (default: 200km). Uses Haversine distance. |
### Utility
| Tool | Description |
|------|-------------|
| `get_flight_url` | Generate a direct Google Flights booking URL. |
| `analyze_layovers` | Analyze connection quality for multi-stop flights. Reports risk level, connection type, aircraft. |
## Example output
### search_flights (with emissions and price context)
```
Flights from SFO to NRT on 2026-06-15:
Price assessment: HIGH ($294 above typical). Range: $500 - $700, typical: $577
Flight 1: $874 | 11h 15m | 0 stop(s) | CO2: 428kg
ZG 25: SFO -> NRT (11h 15m) [aircraft: Boeing 787, seat pitch: 31 inches, CO2: 428kg]
Flight 2: $1310 | 11h 5m | 0 stop(s) | CO2: 545kg
NH 7: SFO -> NRT (11h 5m) [aircraft: Boeing 777, seat pitch: 34 inches, CO2: 545kg]
```
### get_calendar_heatmap
```
Price calendar: SFO -> NRT
61 days of data
Cheapest: $384 (2026-02-12)
Most expensive: $870 (2026-04-13)
Average: $632
2026-02:
12: $384 ***
13: $384 ***
...
20: $540 ***
2026-03:
06: $609 *
...
20: $689
```
### find_nearby_airports
```
Airports near JFK within 150km:
LGA - LaGuardia Airport (New York, US), 17km away
EWR - Newark Liberty International Airport (Newark, US), 33km away
HPN - Westchester County Airport (White Plains, US), 48km away
```
## How it works
There is no official Google Flights API. This server reverse-engineers Google's internal `FlightsFrontendService` endpoint. It extracts not just flights, but hidden metadata: emissions, price assessments, daily price calendars, aircraft types, and seat details.
### Reliability
- **Caching**: 5-minute TTL cache, identical searches don't hit Google twice
- **Retry with backoff**: exponential backoff + jitter on 429/5xx errors, honors `Retry-After` headers
- **Circuit breaker**: stops requests after 5 consecutive failures, auto-recovers after 30s
- **Structural validation**: clear errors when Google changes their response format
- **TLS mitigation**: `undici` with browser-like headers + rotating User-Agents, `fetch` fallback
### Price tracking
Price history is stored in SQLite at `~/.google-flights-mcp/prices.db`. Each call to `track_price` records the current cheapest price and reports the trend compared to previous observations.
## Development
```bash
npm install # Install dependencies
npm run build # Build with tsup
npm test # Run tests (85 tests)
npm run lint # ESLint with FP rules (no-let, immutable-data, no-loop-statements)
npm run typecheck # TypeScript strict type checking
npm run check # typecheck + lint + test (the full CI pipeline)
npm run dev # Build in watch mode
```
### Design
Fully functional TypeScript codebase:
- **No mutation**: all types `readonly`, no `let`/`var`/`.push()`/`for` loops
- **Result monad**: errors are values (`Result<T, E>`), not exceptions
- **Pure/IO separation**: pure transforms are separate from network and disk IO
- **Composition**: `pipe()` + `flatMap()` for chaining fallible operations
See [CLAUDE.md](CLAUDE.md) for architecture details and the Google Flights response format reference.
## Limitations
- **No official API**: uses an undocumented Google endpoint that could change at any time. Structural validation makes breakages obvious.
- **Rate limiting**: Google may throttle heavy use. Built-in retry and circuit breaker handle transient issues.
- **Prices are estimates**: prices reflect query time; they can change before booking.
- **Currency**: determined by Google based on IP/locale.
## Contributing
1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run `npm run check` to verify
5. Open a PR
## License
ISC
