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