ITA Matrix MCP

An MCP server that searches ITA Matrix — Google's fare engine, the one behind a lot of airline and OTA search — so Claude can plan genuinely complex itineraries.

The point of using Matrix over an ordinary flight search is two things it has that consumer sites don't: arbitrary multi-city trips and ITA's routing language, which lets you constrain each leg by carrier, connection point, alliance, or flight count.

Results are real, priced, availability-checked fares. They are not bookable here — take the flight numbers to the airline or an OTA to ticket them.

Tools

Tool	What it does
search_flights	The workhorse. 1–6 legs: one-way, round-trip, multi-city, open-jaw. Per-leg routing codes.
get_itinerary_details	Expands one result into per-segment booking class (RBD), fare basis, and aircraft type.
search_flexible_dates	Scans a date range for the cheapest departure date.
lookup_airport	Resolves place names to IATA codes, including metro codes.
routing_language_reference	The routing-code cheat sheet, so Claude can compose non-trivial codes.

Multi-city

A trip is a list of legs, so every trip shape uses one tool:

{
  "slices": [
    { "origin": "JFK", "destination": "HND", "date": "2026-10-15" },
    { "origin": "HND", "destination": "SIN", "date": "2026-10-22" },
    { "origin": "SIN", "destination": "JFK", "date": "2026-10-30",
      "routing": "AA+ LHR AA+" }   // last leg: American, via Heathrow
  ],
  "cabin": "BUSINESS"
}

Legs need not connect — JFK→LHR then CDG→JFK is a valid open jaw.

Routing codes

Per-leg, and the reason this beats normal search. AA+ = only American, ~ORD = never via Chicago, AA+ DFW AA+ = American connecting at Dallas, F F = exactly two flights. Extension codes go in extraCodes: maxconnect 240, alliance star-alliance, -overnight, f bc=J|C.

Call routing_language_reference for the full syntax.

Note: maxStops is relative to the route minimum, matching Matrix's own semantics — 0 means "no more hops than strictly necessary", which on a long-haul may still involve a connection.

Running it

Two entrypoints share one server definition:

npm install
node src/server.js        # stdio  — local Claude Code / Claude Desktop
node src/http-server.js   # HTTP   — remote, for Claude Desktop connectors

Local (stdio)

claude mcp add ita-matrix -- node D:/path/to/ITA-Matrix-MCP/src/server.js

Remote (Streamable HTTP)

Claude Desktop connects to remote servers from Anthropic's cloud, not from your machine, so the server needs a public HTTPS URL with a valid certificate. localhost and VPN-only hosts will not work. Remote servers are added under Settings → Connectors → Add custom connector; they cannot be configured through claude_desktop_config.json.

Deployed behind Coolify, the container speaks plain HTTP and Coolify's proxy terminates TLS.

Env var	Default	Purpose
PORT	3000	Listen port.
ITA_MATRIX_SECRET_PATH	(unset)	Mounts MCP at /mcp/<secret> instead of /mcp. The URL then acts as the credential.
ITA_MATRIX_ALLOWED_HOSTS	(unset)	Comma-separated Host allowlist, guarding against DNS rebinding.
ITA_MATRIX_API_KEY	auto	Pin the upstream key instead of discovering it.
ITA_MATRIX_TIMEOUT_MS	150000	Upstream timeout. Multi-city searches are slow.

GET /health returns status and active session count, for Coolify's health check.

Each HTTP session gets its own server instance. Idle sessions are swept after 30 minutes, and closed sessions are dropped immediately.

The search cache is process-wide rather than per-session, because MCP sessions are much shorter-lived than a user's train of thought — a reconnect or a 30-minute pause would otherwise throw away results the model was still holding a Search ID for. IDs carry a random suffix (s3-a7f2c9) so they stay unguessable between clients, and entries expire after 6 hours. If Matrix's own pricing session expires first, get_itinerary_details re-runs the original search and re-locates the itinerary by flight number rather than failing.

How it works

Matrix is a Google "Alkali" app fronting the old QPX fare engine. Every call is a single POST to content-alkalimatrix-pa.googleapis.com/batch, with the real JSON-RPC request wrapped in a multipart/mixed envelope. Auth is the public API key that the web app ships to every visitor — no cookies, no OAuth, no bot token.

• POST /v1/search — run a fare search
• POST /v1/summarize — expand one solution (RBDs, aircraft), reusing the search's session + solutionSet, so detail lookups skip the engine re-run
• GET /v1/locationTypes/... — airport autocomplete

Key discovery. The key is not in the page HTML; it's in a gstatic Alkali bundle, which contains about seven AIza… strings of which only two are authorized for this API. So candidates are validated against a cheap endpoint before use, then cached for 30 days, rather than taking the first regex match. If Google rotates keys, the server re-discovers automatically.

Quirks handled. The engine refuses server-side price sorting on multi-slice trips, so sorting is always done client-side. Premium economy is PREMIUM-COACH on the wire while every other cabin uses the plain enum form. Matrix intermittently returns "service is currently unavailable"; that is retried with backoff.

Testing

node test/smoke.mjs                          # offline: stdio, schemas, errors
node test/http-smoke.mjs                     # offline: HTTP session lifecycle
ITA_MATRIX_LIVE=1 node test/smoke.mjs        # live: real searches (slow)
ITA_MATRIX_LIVE=1 node test/http-smoke.mjs

Live tests hit the real service and take 20–60s per search.

Caveats

• Not affiliated with Google, ITA Software, or ITA Matrix.
• Matrix's rate limits are undocumented. A publicly exposed instance draws that traffic to your server's IP.
• If Google starts requiring the bgProgramResponse (WAA) anti-bot token, this approach needs token handling added.
• Prior art: itamx, a Python CLI/MCP for the same API, which is where the protocol details were confirmed.