trvl

trvl — Real travel search for your AI assistant

Ask your AI assistant to plan a real trip, and it actually can. trvl gives Claude, Cursor, Windsurf, Codex, or any MCP-compatible client one smart tool — the travel router — with live access to flights, hotels, rental cars, trains, buses, ferries, price alerts, award sweet spots, weather, and destination intel. Free for noncommercial use, no personal API keys for default search, no signup. One binary.

You: I have €300 and a free weekend. Surprise me.

Illustrative response shape (prices are examples): Dubrovnik, Croatia 🇭🇷 — ✈️ Ryanair HEL→DBV €167 RT · 🏨 Old Town Studios 4.6★ €84 · 🌡️ 26°C, sunny.

📊 Naive €350 → optimized €251 → saved €99 (28%) by flying Friday and splitting airlines.

▶ Try it live, no install: socialistic.ai/trvl-travel-mcp (community-hosted).

How it works, in one paragraph

trvl is a single binary that runs on your machine. Your AI client talks to it over MCP; it queries flight, hotel, transport, weather, and places sources, then merges, de-duplicates and optimizes the results before handing back one answer. Most sources are free public endpoints, so there is nothing to sign up for. The ones behind bot protection may reuse the browser session you already have, which is the one thing worth reading about before you install: see What trvl reads, and what it keeps.

trvl speaks the two latest MCP revisions: 2026-07-28 and 2025-11-25. An initialize with no _meta is answered as 2025-11-25, whether the handshake names 2025-11-25 or 2026-07-28, and that answer includes ping and resources/subscribe. _meta of 2026-07-28 on an initialize selects the 2026 shape. A client that sends 2026-07-28 in _meta["io.modelcontextprotocol/protocolVersion"] on each request gets server/discover, resultType, cache hints on the list and read endpoints, and subscriptions/listen instead of resource subscribe. Any other _meta protocol version returns JSON-RPC -32022 with data.supported and data.requested. On HTTP the MCP-Protocol-Version header has to match that field; a 2026 header alone is -32020. A 2026 request must also send Mcp-Method (and Mcp-Name for tools/call, resources/read, and prompts/get).

Why trvl, not the alternatives

• Whole journey, door to door. It plans the entire trip across modes — home to airport, flight, arrival transfer, hotel, onward train — and prices each leg in its real mode. Most tools stop at one flight, one hotel.
• No personal API key for default search. There is no Amadeus key to apply for, subscription, or per-call bill on the default paths. Optional providers switch on when you supply their credentials; none is required for the default flight, hotel, or ground searches.
• Your assistant, your machine. One local binary, any MCP client, not locked to a vendor. Searching sends the query to the providers being searched, the same as any travel site would: route, dates and traveller count go to Google, Kiwi, Booking and the rest. What trvl keeps for itself stays on your machine, apart from any webhook you configure yourself. A released build sends one daily heartbeat to https://telemetry.revaluator.ai/v1/heartbeat, and you can switch that off. TRVL_TELEMETRY_ENDPOINT replaces that URL. Both are spelled out below.
• It optimizes, not just lists. Shift-day pricing, split-airline routing, hidden-city checks, award sweet spots, round-trip fares. It hands back the cheaper option and shows what it saved.
• It is honest when a source fails. Typed statuses and labelled estimates, never an empty result dressed up as "nothing found."

Full head-to-head against Google Flights, KAYAK, Skyscanner, Kiwi, and other travel MCPs: docs/COMPARISON.md.

What it can do

Is this for you?

Yes if you already plan trips with an AI assistant and want it to search real flights, hotels, trains, buses, ferries, and transfers instead of guessing — or if you're building an app that needs travel intent without a paid travel API.

Probably not if you just want to book on a website (use Google Flights), or you want a hosted product with an account and dashboard. trvl is a tool you run, not a service you log into.

Full positioning: docs/POSITIONING.md.

Install

Let your AI do it — paste into Claude Code, Cursor, Windsurf, or Codex:

Read https://raw.githubusercontent.com/MikkoParkkola/trvl/main/AGENTS.md and set up trvl

It installs the binary, wires the MCP server, installs the skill, and verifies everything. Under a minute.

Or by hand:

brew install MikkoParkkola/tap/trvl   # install

trvl mcp install # auto-detects your AI client

Restart your client. trvl mcp install --client targets a specific one (10 supported: Claude Desktop/Code, Cursor, Windsurf, Codex, VS Code, Zed, Gemini, Amazon Q, LM Studio).

More ways to install (Go, Docker, raw binary, manual config)

# Direct binary (no Homebrew)

TRVL_VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/MikkoParkkola/trvl/releases/latest | sed 's#.*/v##')" curl -fsSL "https://github.com/MikkoParkkola/trvl/releases/download/v${TRVL_VERSION}/trvl_${TRVL_VERSION}_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz -C /usr/local/bin trvl

Go

go install github.com/MikkoParkkola/trvl/cmd/trvl@latest

Docker

docker run --rm ghcr.io/mikkoparkkola/trvl flights HEL NRT 2027-06-15

Build from source

git clone https://github.com/MikkoParkkola/trvl.git && cd trvl && make build

Claude Code CLI

claude mcp add trvl --transport stdio -- trvl mcp

Manual JSON (Claude Desktop, Cursor, Windsurf, etc.)

{ "mcpServers": { "trvl": { "command": "trvl", "args": ["mcp"] } } }

Try it

Paste any of these to your assistant once trvl is wired:

Find the cheapest realistic trip from Helsinki for the long weekend of July 1–5, nonstop, hotel near the center.

Compare award sweet spots HEL→LHR business on Aug 15 with 80k Amex MR + 20k Virgin points. Create a mistake-fare watch for HEL→BCN, July 1–8, and alert me below €90.

More starter prompts and what good answers look like: docs/DEMO.md.

Why trust it

An AI agent acts on trvl's output without a human checking every result, so the bar is correctness, not just coverage.

• It tells you when it can't. A blocked or rate-limited provider returns a typed status (AKAMAI_BLOCK, RATE_LIMITED, BOOKING_COOKIES_MISSING) with a fix hint, instead of a fake "nothing found." Estimated values are labelled; currency-mismatched totals are skipped, not faked.
• Tested more than it is written. More test code than source, race-checked on macOS, Linux, and Windows. A smoke gate runs the packaged binary before any release — a build that doesn't run can't ship.
• It degrades gracefully. Providers run concurrently with per-provider timeouts; one source failing returns partial results instead of aborting the search.
• It's observable. trvl status (or the local /dashboard in HTTP mode) shows per-provider success rate, latency, freshness, and circuit-breaker state.

On hotel prices specifically. Hotel metasearch exposes list-level rates first; some are real, some only firm up after the property detail page reveals the room/tax/cancellation matrix. So trvl separates discovery (search_hotels — fast, lead-in prices) from decisions (search_accommodations — verifies room-level offers before ranking) and drill-down (search_hotels_with_details, hotel_rooms). It provides booking links for manual handoff but never books, holds, or guarantees a rate. Detail: docs/PROVIDERS.md.

What trvl reads, and what it keeps

Two things happen without you asking for them. Neither is obvious, so both are stated here rather than left to a linked page.

It reads your browser's cookies, automatically. Hotel and rail sites put bot protection in front of their search APIs, and trvl gets past it by reusing the browser session you already have — that is why searches work with no API key. The reads start when trvl launches, before any search. No flag turns them on. On macOS, browser cookie stores are encrypted, so reading them means Keychain access and you should expect a Keychain prompt. What is read is your own session cookies for the site being searched, and they go into the request t