google-flights-mcp

# Google Flights MCP Server

<!-- mcp-name: com.hasdata/google-flights -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client one Google Flights tool. Search one-way, round-trip and multi-city itineraries with fares, flight legs, carbon emissions and price history, all as structured JSON, with no Google account and no retired travel API to work around.

```
https://mcp.hasdata.com/api/mcp?apis=google_travel_flights
```

[![Glama score](https://glama.ai/mcp/servers/HasData/google-flights-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/google-flights-mcp)
[![tool contract](https://github.com/HasData/google-flights-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/google-flights-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-1-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=google-flights-mcp), free to create with no card, and the trial covers about 66 calls at the 15-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run and no Google account anywhere in the flow. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/google-flights-mcp` on npm and `hasdata-google-flights-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=google_travel_flights` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http google-flights "https://mcp.hasdata.com/api/mcp?apis=google_travel_flights" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=google_travel_flights` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/google-flights-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-flights": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-flights-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "google-flights": {
      "command": "uvx",
      "args": ["hasdata-google-flights-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "google-flights": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_travel_flights",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "google-flights": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_travel_flights",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "google-flights": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_travel_flights",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent picks the tool itself. Each is annotated with the calls it takes, because every successful call costs 15 credits.

> Find one-way flights from JFK to London Heathrow on September 15, sorted by price, and give me the three cheapest with airline and carbon estimate.

*One call, 15 credits. Fares, legs and emissions all come back together.*

> Same route but non-stop only, in business class, and tell me which option has the lowest emissions.

*One call, 15 credits. Cabin and stops are filters on the one request.*

> Is $295 a good price for JFK to LHR right now, given the price history?

*One call, 15 credits. The response carries `priceInsights` with a typical range and a price level.*

> Round trip JFK to LHR, out September 15 back September 22, cheapest fare.

*Two calls, 30 credits. Google returns outbound options first, then the return leg is a second call keyed by the option you pick.*

A round trip is two calls by design. The first returns outbound itineraries each with a `departureToken`, and you pass that token back to get the matching return flights. One-way and the price check are a single call each.

## Tools

One tool, read-only. The sample below is trimmed from a real call, and fares move constantly. Read it as a shape. The tool name links to its endpoint reference, which carries the full parameter list.

The sample is the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Get Google Flights results

[`hasdata_google_travel_flights_getGoogleFlights`](https://docs.hasdata.com/apis/google-travel/flights?utm_source=github&utm_medium=syndication&utm_campaign=google-flights-mcp)

Itineraries for a route and date, with fares, legs, emissions and price history.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `departureId` | string | yes | IATA code such as `JFK`, or a location kgmid like `/m/02_286`. Comma-separate several airports |
| `arrivalId` | string | yes | Same format as `departureId` |
| `outboundDate` | string | yes | `YYYY-MM-DD` |
| `type` | string | | `roundTrip` by default, `oneWay`, or `multiCity` with `multiCityJson` |
| `returnDate` | string | | Required when `type` is `roundTrip` |
| `travelClass` | string | | `economy`, `premiumEconomy`, `business` or `first` |
| `stops` | string | | `nonStop`, `oneStopOrFewer` or `twoStopsOrFewer` |
| `sortBy` | string | | `topFlights` default, plus `price`, `duration`, `emissions`, `departureTime`, `arrivalTime` |
| `adults` / `children` / `infantsInSeat` / `infantsOnLap` | number | | Passenger mix |
| `maxPrice` / `maxDuration` / `bags` | number | | Ceilings and carry-on count |
| `includeAirlines` / `excludeAirlines` | string | | Comma-separated IATA airline codes, one or the other, not both |
| `departureToken` | string | | Select an outbound option and fetch its return or next leg |
| `bookingToken` | string | | Fetch booking options for a chosen itinerary |
| `currency` / `gl` / `hl` | string | | Currency and the country and language of the search |
| `deepSearch` | boolean | | Match what Google shows in a browser, slower to return |

The reference also documents `includeConnections`, `excludeConnections`, `layoverDuration`, `outboundTimes`, `returnTimes`, `showHidden`, `lessEmissions` and `multiCityJson`.

Results split into `bestFlights` and `otherFlights`. Each itinerary carries `price`, `type`, `totalDuration` in minutes, a `flights` array of legs, a `carbonEmissions` object, and a `bookingToken`. Each leg holds the `departureAirport` and `arrivalAirport` (each with `id`, `name` and local `time`), `duration`, `airline`, `flightNumber`, `airplane`, `legroom`, `travelClass`, an `extensions` array, and `oftenDelayedByOver30Min` on legs Google flags. A non-stop itinerary has one leg, a connection has several.

> `carbonEmissions` is in grams, not kilograms. `thisFlight: 433000` is 433 kg. `differencePercent` compares it to `typicalForThisRoute`, so a negative number is a greener-than-average flight.

```json
{
  "price": 295,
  "type": "One way",
  "totalDuration": 415,
  "flights": [
    {
      "departureAirport": { "id": "JFK", "name": "John F. Kennedy International Airport", "time": "2026-09-15 8:15" },
      "arrivalAirport": { "id": "LHR", "name": "Heathrow Airport", "time": "2026-09-15 20:10" },
      "duration": 415,
      "airline": "Virgin Atlantic",
      "flightNumber": "VS 26",
      "airplane": "Boeing 787",
      "travelClass": "Economy"
    }
  ],
  "carbonEmissions": { "thisFlight": 367000, "typicalForThisRoute": 419000, "differencePercent": -12 },
  "bookingToken": "W1t7..."
}
```

`priceInsights` sits alongside the itineraries with `lowestPrice`, a `typicalPriceRange`, a `priceLevel` such as `typical`, and a `priceHistory` of `[timestamp, price]` points. `airports` echo