This server provides tools to search, analyze, and retrieve detailed flight itineraries via Google's ITA Matrix fare engine, supporting complex multi-city searches with per-leg routing constraints, flexible date scanning, and airport code lookup.
Search flights (search_flights): Search one-way, round-trip, multi-city, or open-jaw itineraries with up to 6 legs. Each leg can use a routing code to constrain carriers, connections, alliances, or flight counts. Options include cabin class, passenger types (adults, children, seniors, youths, infants), currency, sales city, max stops, departure time windows, and flexible dates (flexDays). Returns a Search ID for later detail retrieval.
Get itinerary details (get_itinerary_details): Expand a specific itinerary from a prior search to reveal per-segment details: booking class (RBD), fare basis codes, operating flight numbers, and aircraft type.
Search flexible dates (search_flexible_dates): Scan a range of departure dates (up to 21) to find the cheapest fare for each day, helping identify optimal travel times. Supports round-trip length, routing codes, cabin, and passenger options.
Lookup airport (lookup_airport): Resolve partial city or airport names to IATA codes, including metro codes (e.g., NYC for JFK, EWR, LGA).
Routing language reference (routing_language_reference): Access full syntax documentation for ITA's routing language, enabling complex constraints like carrier pinning (AA+), connection forcing/exclusion (~ORD), alliance filters, stop counts, and fare-bucket filters.
Results represent real, availability-checked fares, but ticketing must be done directly with airlines or online travel agencies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ita-matrix-mcp Find a business-class trip JFK to HND to SIN and back, late October."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | What it does |
| The workhorse. 1–6 legs: one-way, round-trip, multi-city, open-jaw. Per-leg routing codes. |
| Expands one result into per-segment booking class (RBD), fare basis, and aircraft type. |
| Scans a date range for the cheapest departure date. |
| Resolves place names to IATA codes, including metro codes. |
| The routing-code cheat sheet, so Claude can compose non-trivial codes. |
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.
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:
maxStopsis relative to the route minimum, matching Matrix's own semantics —0means "no more hops than strictly necessary", which on a long-haul may still involve a connection.
Related MCP server: cheapflights-mcp
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 connectorsclaude mcp add ita-matrix -- node D:/path/to/ITA-Matrix-MCP/src/server.jsClaude 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 |
|
| Listen port. |
| (unset) | Mounts MCP at |
| (unset) | Comma-separated Host allowlist, guarding against DNS rebinding. |
| auto | Pin the upstream key instead of discovering it. |
|
| 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.
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.
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.mjsLive tests hit the real service and take 20–60s per search.
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.
Show per-segment detail for one itinerary from a previous search: operating flight numbers, booking class (RBD), fare basis codes, and aircraft type. Reuses the earlier search session, so it is fast.
| Name | Required | Description | Default |
|---|---|---|---|
| rank | Yes | Which itinerary — the #N shown in the search results. | |
| searchId | Yes | Search ID from search_flights, e.g. "s1". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the read-only nature implicitly by focusing on 'show' details, specifies the output granularity (per-segment) and exact data points, and notes session reuse and performance ('fast'). Missing are error conditions, but for a detail-retrieval tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: the first states the purpose and output fields, the second adds behavioral context about session reuse and speed. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers the essential context: what it does, what it returns, when it is used, and a performance note. It implicitly states the prerequisite (a prior search) and the field list serves as the return-value specification. No critical gaps for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (searchId, rank) already described in the schema. The description adds context that the itinerary is from a previous search, but no new parameter-specific semantics beyond the schema's explicit examples and definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Show') and resource ('per-segment detail for one itinerary from a previous search') with specific fields (operating flight numbers, booking class, fare basis codes, aircraft type). This differentiates it from siblings like search_flights, which perform the initial search, and lookup_airport, which handles airport lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for expanding a previously returned itinerary ('from a previous search', 'Reuses the earlier search session'), providing clear context for when to use it. It does not explicitly name an alternative or state when not to use it, but the session-reuse detail effectively excludes standalone use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a partial city or airport name to IATA codes. Use this when the user names a place rather than a code, or to find the metro code that covers every airport in a city.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Partial name or code, e.g. "milan", "JFK". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It discloses the tool's ability to handle partial names and return metro codes, which is useful. However, it does not explain what the tool returns (e.g., multiple matches, structure), how it handles ambiguity or no results, or any other edge cases. For a lookup tool, this leaves some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose in the first sentence. It is concise, contains no filler, and every sentence adds useful context: the first defines the function, the second provides usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 parameters, no output schema), and the description provides purpose and usage, but it omits explanation of the 'limit' parameter and does not mention what the response looks like. Given no annotations and no output schema, the description is somewhat incomplete for an agent to fully anticipate the tool's behavior, but it covers the primary intent adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the 'query' parameter with examples, and the tool description reinforces its purpose by mentioning partial names and metro codes. However, the 'limit' parameter is not mentioned in the description at all, and its schema lacks a description. With 50% schema coverage, the description does not compensate for the missing limit semantics, leaving the agent to infer its role from the name and constraints alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: resolving partial city or airport names to IATA codes. It uses the specific verb 'resolve' and names the resource ('partial city or airport name to IATA codes'). This sets it apart from sibling tools like search_flights or get_itinerary_details, which deal with routing and itineraries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Use this when the user names a place rather than a code, or to find the metro code that covers every airport in a city.' This gives clear context and effectively distinguishes it from alternatives. It also implies that for other operations (e.g., flight search), other tools should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full syntax for the routing and extraCodes fields: carrier pinning, forced connection points, alliances, exclusions, stop counts, and fare-bucket filters. Read this before composing a non-trivial routing code.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining what the tool returns—a comprehensive syntax reference. It discloses the scope of content covered, which is the key behavioral trait for a documentation tool. It doesn't detail the output format, but the nature of a reference makes that less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with a front-loaded title and a concise list of topics. Every word earns its place, and the 'Read this before...' directive adds practical utility without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently conveys the tool's purpose and scope for a simple zero-parameter reference. It doesn't enumerate every syntax detail, but that's expected—the tool itself provides the full syntax. It's complete enough to guide invocations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to clarify. The description instead explains what the reference covers, which is useful context beyond the empty schema. Baseline 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as providing the full syntax for the 'routing' and 'extraCodes' fields, listing specific topics like carrier pinning, alliances, and exclusions. This distinguishes it from sibling search tools, establishing it as a reference/documentation resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises reading this before composing a non-trivial routing code, which is clear when-to-use guidance. It doesn't explicitly exclude other scenarios or name alternative tools, but the context of siblings makes its purpose unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a range of departure dates and report the cheapest fare on each, to find when to fly. Runs one search per date, so keep ranges modest (a 14-day scan takes several minutes). For a single date with ±flexibility, use search_flights with flexDays instead.
| Name | Required | Description | Default |
|---|---|---|---|
| cabin | No | Minimum cabin. Default COACH. | |
| adults | No | ||
| origin | Yes | ||
| youths | No | ||
| endDate | Yes | Last departure date, YYYY-MM-DD. | |
| routing | No | Routing code applied to every leg. | |
| seniors | No | ||
| children | No | ||
| currency | No | ISO 4217, e.g. "USD", "EUR". | |
| maxDates | No | Cap on dates to probe. Default 10. | |
| maxStops | No | Stops allowed RELATIVE TO the minimum possible for the route (Matrix semantics), not absolute. 0 = only the shortest-hop routings. Default 1. | |
| salesCity | No | IATA city code for point of sale. Changes which fares are filed and offered — useful for finding cheaper origin-country pricing. | |
| startDate | Yes | First departure date, YYYY-MM-DD. | |
| destination | Yes | ||
| infantsInLap | No | ||
| infantsInSeat | No | ||
| tripLengthDays | No | Nights away for a round-trip. Omit or 0 for one-way. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, and it does: 'Runs one search per date, so keep ranges modest (a 14-day scan takes several minutes).' This reveals a key performance characteristic. However, it does not describe the output format or any other behavioral details, though as a search tool there are few side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, then a performance caveat, then an explicit alternative. Every word contributes useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, no output schema), the description gives a clear high-level purpose, a performance warning, and a usage boundary. It could describe the return format or key required parameters, but the core usage is well covered for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 53%, so the schema already explains many parameters. The description adds context about range size and performance, which indirectly relates to startDate/endDate and maxDates, but it does not explain any specific parameter in detail beyond what the schema provides. It does not compensate significantly for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Scan a range of departure dates and report the cheapest fare on each,' using specific verbs and a resource. It also distinguishes from the sibling search_flights by explicitly directing users with single-date flexibility to that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'For a single date with ±flexibility, use search_flights with flexDays instead.' This tells the agent when not to use this tool and names the alternative. It also advises keeping ranges modest due to the one-search-per-date behavior, giving practical usage constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ITA Matrix for itineraries. A trip is a list of legs (slices): • 1 slice = one-way • 2 slices = round-trip (second slice reverses the first) • 3+ = multi-city / open-jaw — legs need not connect Each leg takes its own routing code, so you can pin a carrier, force a connection city, or require a specific number of flights per leg. Expect 20-60s. Returns ranked itineraries and a Search ID for get_itinerary_details.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Client-side sort. Default price. | |
| cabin | No | Minimum cabin. Default COACH. | |
| limit | No | How many itineraries to return. Default 10. | |
| adults | No | ||
| slices | Yes | The legs, in travel order. For a round-trip, add a second slice with origin/destination swapped. | |
| youths | No | ||
| seniors | No | ||
| children | No | ||
| currency | No | ISO 4217, e.g. "USD", "EUR". | |
| maxStops | No | Stops allowed RELATIVE TO the minimum possible for the route (Matrix semantics), not absolute. 0 = only the shortest-hop routings. Default 1. | |
| salesCity | No | IATA city code for point of sale. Changes which fares are filed and offered — useful for finding cheaper origin-country pricing. | |
| infantsInLap | No | ||
| infantsInSeat | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses latency ('Expect 20-60s'), return value ('ranked itineraries and a Search ID'), and slice semantics. It does not cover error cases or rate limits, but the disclosed behaviors are meaningful for invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: two sentences plus a bulleted list convey the core concept, routing flexibility, latency, and follow-up flow. Every sentence earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (13 params, multi-slice logic) and has no output schema. The description covers the essential mental model, routing mechanism, latency, and connection to get_itinerary_details. It does not enumerate return field details or error handling, but for a search tool paired with a details tool, it provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 54%, so the description adds valuable extra meaning. It explains the slices parameter's semantics (one-way/round-trip/open-jaw) and the routing parameter's purpose (pin carrier, force connection, control flight count). Other parameters like passenger counts remain undocumented in both schema and description, but the most complex parameters receive useful added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search ITA Matrix for itineraries' – a specific verb+resource pair. It then distinguishes trip shapes (one-way, round-trip, multi-city) and explicitly mentions the Search ID for get_itinerary_details, clearly separating this tool from the details tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: slice count determines trip type, routing codes allow complex legs, and results feed into get_itinerary_details. It does not explicitly contrast with search_flexible_dates or state when not to use this tool, so it stops short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_itinerary_detailslookup_airportrouting_language_referencesearch_flexible_datessearch_flightsScored across 5 tools
Each tool has a distinct purpose: search_flights for itinerary search, search_flexible_dates for date-range price scans, get_itinerary_details for segment-level details, lookup_airport for IATA code resolution, and routing_language_reference for syntax documentation. The only overlap is between the two search tools, but their descriptions clearly differentiate them (itinerary search vs. date-range scanning).
All tool names use snake_case and mostly follow a verb_noun pattern (search_flights, get_itinerary_details, lookup_airport). search_flexible_dates adds an adjective but remains consistent. routing_language_reference is a noun phrase rather than verb-led, but it still reads clearly and does not break the overall style.
With 5 tools, the server is well-scoped for ITA Matrix functionality. Each tool covers a necessary aspect: searching, exploring dates, getting details, resolving airports, and providing routing-language guidance. No redundant or extraneous tools.
The tool set covers the core ITA Matrix workflow: search flight itineraries, scan flexible dates, retrieve detailed segment information, look up airport codes, and understand routing language syntax. There are no obvious missing operations for typical fare-searching tasks, and the provided tools form a complete lifecycle for flight exploration.
Flight search MCP server providing search, pagination, and itinerary details for AI assistants.
Search and compare flight offers through a cache-aware Streamable HTTP MCP server for AI agents.
Geo-based flight search MCP server. Find more flights between any two places on earth
Skiplagged MCP Server for flight search, hotel booking, and travel planning
