Skip to main content
Glama
README.md
# travel-mcp

Formerly flights-mcp.

An MCP server that searches Google Flights through
[SerpAPI](https://serpapi.com/google-flights-api), locally over stdio or, for
ChatGPT, over HTTP. It follows the idea of
[ravinahp/flights-mcp](https://github.com/ravinahp/flights-mcp) but shares no
code with it. It uses SerpAPI instead of Duffel, so low-cost carriers such as
Ryanair appear as they do on Google Flights. It only searches; it cannot book.

## Tools

| Tool | What it does |
| --- | --- |
| `search_flights` | One-way or round-trip search. Several airports per side, e.g. `BRU,CRL`. Filters for stops, cabin, times, price, airlines, carry-on bags. |
| `search_multi_city` | Two or more legs; returns options for the first leg. |
| `get_next_flights` | With an offer's `departure_token`: the return flights of a round trip, or the next multi-city leg. |
| `get_booking_options` | With an offer's `booking_token`: where the itinerary can be booked and at what price. |

Every tool call is one SerpAPI search and counts against the monthly quota.
SerpAPI needs the original search parameters with a token, so each token the
server returns carries them: `base64url(zlib(JSON))`, a dot, and SerpAPI's own
token. Tokens therefore keep working after a restart of the server. When a token
comes back, the server accepts only the parameters its own search tools set, and
rejects anything else without calling SerpAPI.

Defaults: prices in EUR, Google Flights for Belgium (`gl=be`), English labels
(`hl=en`).

## Setup

Store the SerpAPI key in the login Keychain. `security` prompts for it, so it
stays out of the shell history:

```zsh
security add-generic-password -U -a "$USER" -s serpapi-api-key -w
```

Do not add `-T ""`: the server reads the key through `/usr/bin/security`, and a
confirmation dialog on every search would block it.

Install the dependencies and register the server in Claude Code for all
projects:

```zsh
cd ~/Repos/travel-mcp
uv sync
claude mcp add --scope user travel -- ~/.local/bin/uv --directory ~/Repos/travel-mcp run travel-mcp
```

Restart Claude Code; the tools appear as `mcp__travel__*`.

## HTTP for ChatGPT

`travel-mcp-http` serves the same tools over stateless streamable HTTP on port
8000, only at `/<TRAVEL_MCP_PATH>/mcp` and only for the Host header
`TRAVEL_MCP_HOST`. Every other path returns 404, and another host returns 421.
ChatGPT offers no static token or API key, so the path is the secret: at least
32 URL-safe characters. The server writes no access log, because that would log
the path. Without both variables, or with a path that is too short, it refuses to
start. Hosting on Azure is described in `docs/azure-plan.md`.

## Deploying to Azure

The `Dockerfile` builds `travel-mcp-http` for linux/amd64, as a non-root user.
`deploy_azure.sh` builds it on the Mac from main's HEAD and pushes it to the
registry of pluk-de-dag, because ACR Tasks do not exist in Belgium Central. It
then rolls it out to `app-travel-mcp`, using Steven's own `az login`:

```zsh
./deploy_azure.sh
./deploy_azure.sh --build-only
./deploy_azure.sh 1a2b3c4
```

The first command builds and rolls out. The second only builds and pushes: that
is the first image, before Terraform creates the app. The third rolls back to an
image already in the registry.

After a rollout the script checks that `/mcp` returns 404 and that the secret
path answers `initialize` with 200. It reads the path from the Key Vault and
passes it to curl on stdin, so the path stays out of the process list.

## How the key is handled

- On the Mac, the server reads the key from the Keychain at each search, in its
  own process. There it is never put in an environment variable, a file or a
  tool result.
- In a container, where there is no Keychain, the server reads `SERPAPI_API_KEY`
  instead. The container platform fills it from a secret store
  (`docs/azure-plan.md`). When the variable is set it takes precedence, and an
  empty value is an error rather than a silent fallback to the Keychain.
- Errors the server expects, such as a wrong date, an invalid token or a SerpAPI
  error, reach the model with their message. Any other failure shows only
  "Error executing tool <name>".
- SerpAPI takes `api_key` as a URL parameter. The server runs its loggers at
  WARNING, because httpx logs every request URL at INFO and MCP clients keep
  server stderr in their logs. A test checks this.
- Error messages carry SerpAPI's error text or the HTTP status, never the URL.

## Development

```zsh
uv sync --extra test
uv run pytest
```

The tests use `httpx.MockTransport` and never call SerpAPI.

Checked against one live round trip (CRL–BCN on Ryanair, 2026-11-20); the
SerpAPI documentation does not describe these points:

- Round-trip prices in the outbound list are totals for the whole trip: the
  outbound offer, its return flight and the booking option all showed EUR 59.
- A booking option bookable as one ticket comes as `together` with
  `book_with`, `airline` (true when booked with the airline itself),
  `marketed_as` (flight numbers), `price` and `baggage_prices` (text such as
  `1 carry-on bag: 25-72`). Separate tickets (`departing` and `returning`)
  have not been seen yet.
- `google_flights_url` was present in all three responses, but one trip does
  not prove that it is always there; the tools return `null` when it is
  missing.

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct role: single/round-trip flight search, multi-city search, continuation of an existing search via token, and booking option retrieval. The boundary between search_flights and search_multi_city is clear from the trip type, and the token-based tools are explicitly scoped.

Naming Consistency5/5

All tools use consistent snake_case verb_noun naming: search_flights, search_multi_city, get_next_flights, get_booking_options. The pattern is predictable and easy for an agent to follow.

Tool Count5/5

Four tools are well-scoped for a focused flight-search server. Each tool earns its place in the search and booking-option workflow, with no redundant or filler tools.

Completeness4/5

The surface covers core flight search workflows: one-way/round-trip, multi-city, continuation, and booking options. Minor gaps exist around ancillary needs like airport lookup or explicit offer details, but core workflows are covered without dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues