trvl

trvl — 为你的 AI 助手提供真实旅行搜索

让你的 AI 助手规划一次真实旅行，它真的能做到。 trvl 为 Claude、Cursor、Windsurf、Codex 或任何兼容 MCP 的客户端提供一个智能工具——travel 路由器，可实时查询航班、酒店、租车、火车、巴士、渡轮、价格提醒、里程兑换优惠、天气和目的地信息。非商业用途免费，默认搜索无需个人 API 密钥，无需注册。一个二进制文件。

你： 我有 €300，还有一个空闲周末。给我一个惊喜吧。

示例回复形式（价格仅供示例）： 克罗地亚，杜布罗夫尼克 🇭🇷 — ✈️ Ryanair HEL→DBV €167 往返 · 🏨 老城区公寓 4.6★ €84 · 🌡️ 26°C，晴。 📊 原始方案 €350 → 优化后 €251 → 节省 €99（28%），方法是周五出发并拆分航空公司。

▶ 在线试用，无需安装： socialistic.ai/trvl-travel-mcp（由社区托管）。

一段话了解工作原理

trvl 是一个在本机运行的单一二进制文件。你的 AI 客户端通过 MCP 与它通信；它会查询航班、酒店、交通、天气和地点数据源，然后合并、去重并优化结果，最后返回一个答案。大多数数据源都是免费的公共端点，因此无需注册。受机器人防护机制保护的数据源可能会重用你已有的浏览器会话。安装前值得了解的只有这一点：请参阅trvl 会读取什么，以及会保留什么。

trvl 支持最新的两个 MCP 版本：2026-07-28 和 2025-11-25。对于不带 _meta 的 initialize，无论握手指定 2025-11-25 还是 2026-07-28，都会按 2025-11-25 响应，且响应中包含 ping 和 resources/subscribe。在 initialize 中使用 2026-07-28 的 _meta，则会选择 2026 版格式。若客户端在每个请求的 _meta["io.modelcontextprotocol/protocolVersion"] 中发送 2026-07-28，则会获得 server/discover、resultType、列表和读取端点的缓存提示，以及 subscriptions/listen（而非资源订阅）。任何其他 _meta 协议版本都会返回 JSON-RPC -32022，并包含 data.supported 和 data.requested。在 HTTP 上，MCP-Protocol-Version 标头必须与该字段一致；仅有 2026 标头会返回 -32020。2026 请求还必须发送 Mcp-Method（对 tools/call、resources/read 和 prompts/get，还必须发送 Mcp-Name）。

为什么选择 trvl，而非其他方案

• 覆盖全程，门到门。 它会规划涵盖多种交通方式的完整行程——从家到机场、搭乘航班、抵达后的接驳、酒店以及后续火车——并按实际交通方式为每一段行程报价。大多数工具只处理一趟航班或一家酒店。
• 默认搜索无需个人 API 密钥。 默认路径无需申请 Amadeus 密钥、订阅，也无需按调用付费。提供凭据后即可启用可选服务提供商；默认的航班、酒店或地面交通搜索都不要求提供凭据。
• 你的助手，你的机器。 一个本地二进制文件，适用于任何 MCP 客户端，不受供应商绑定。搜索时会将查询发送给正在搜索的数据提供商，与任何旅行网站的做法相同：路线、日期和旅客人数会发送给 Google、Kiwi、Booking 等服务。除非你自行配置了 Webhook，否则 trvl 自行保留的数据会留在你的机器上。已发布的构建版本每天会向 https://telemetry.revaluator.ai/v1/heartbeat 发送一次心跳，你可以关闭此功能。TRVL_TELEMETRY_ENDPOINT 可替换该 URL。下文会详细说明这两项内容。
• 它会优化，而不只是列出结果。 提供可调整日期的价格、拆分航空公司的路线、隐藏城市检查、奖励兑换高价值选择以及往返票价。它会返回更便宜的选项，并展示节省的金额。
• 数据源出错时，它会如实说明。 提供带类型的状态和明确标注的估算值，绝不会把空结果伪装成“未找到结果”。

与 Google Flights、KAYAK、Skyscanner、Kiwi 及其他旅行 MCP 的完整横向对比，请参阅：docs/COMPARISON.md。

功能一览

适合你吗？

如果你已经在用 AI 助手规划旅行，并希望它搜索真实的航班、酒店、火车、巴士、渡轮和接驳交通，而不是凭空猜测，那么适合；如果你正在开发一款无需付费旅行 API、但需要识别旅行意图的应用，也适合。

如果你只想在网站上预订（请使用 Google Flights），或者想要带账户和控制面板的托管产品，那么可能不适合。trvl 是你运行的工具，而不是你登录使用的服务。

完整定位说明：docs/POSITIONING.md。

安装

让 AI 帮你安装——将以下内容粘贴到 Claude Code、Cursor、Windsurf 或 Codex 中：

阅读 https://raw.githubusercontent.com/MikkoParkkola/trvl/main/AGENTS.md 并设置 trvl

它会安装二进制文件、配置 MCP 服务、安装技能并验证所有内容。不到一分钟即可完成。

或者手动安装：

brew install MikkoParkkola/tap/trvl   # install
trvl mcp install                       # auto-detects your AI client

重启客户端。trvl mcp install --client <name> 可指定目标客户端（支持 10 种：Claude Desktop/Code、Cursor、Windsurf、Codex、VS Code、Zed、Gemini、Amazon Q、LM Studio）。

# 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"] } } }

试用

配置好 trvl 后，将以下任意内容粘贴给你的助手：

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.

更多入门提示词和优质回答示例：docs/DEMO.md。

为什么值得信赖

AI Agent 会依据 trvl 的输出采取行动，而不会由人工逐一核查每项结果，因此首要标准是正确性，而不只是覆盖范围。

• 无法完成时会明确告知。 服务商遭到拦截或受到速率限制时，会返回带类型的状态（AKAMAI_BLOCK、RATE_LIMITED、BOOKING_COOKIES_MISSING）和修复提示，而不是假装“没有找到结果”。估算值会明确标注；币种不匹配的总价会被跳过，而不是伪造。
• 测试代码多于源代码。 测试代码多于源代码，并在 macOS、Linux 和 Windows 上通过竞态检测。每次发布前都会通过冒烟测试门禁运行打包后的二进制文件——无法运行的构建不会发布。
• 能够平稳降级。 各服务商并行运行，并设有独立超时；一个来源出错时会返回部分结果，而不是中止搜索。
• 运行状态可观测。 trvl status（或 HTTP 模式下的本地 /dashboard）会显示各服务商的成功率、延迟、数据新鲜度和熔断器状态。

关于酒店价格的特别说明。 酒店元搜索首先展示列表级价格；其中有些是真实价格，有些则要等酒店详情页显示客房／税费／取消政策矩阵后才能确定。因此，trvl 将发现（search_hotels——速度快，显示起始价格）、决策（search_accommodations——对房间级优惠进行验证后再排序）和深入查询（search_hotels_with_details、hotel_rooms）区分开来。它会提供预订链接，供用户手动跳转，但绝不会代为预订、保留房间或保证价格。详情：docs/PROVIDERS.md。

trvl 会读取什么，以及会保留什么

有两件事会在你不知情的情况下发生。它们都不太明显，因此这里一并说明，而不是留给链接页面介绍。

它会自动读取你浏览器的 Cookie。 酒店和铁路网站会在搜索 API 前设置机器人防护，trvl 通过重复使用你已有的浏览器会话来绕过防护——这就是为什么无需 API 密钥也能搜索。trvl 启动时就会开始读取 Cookie，早于任何搜索。没有任何标志可以开启这些读取。在 macOS 上，浏览器的 Cookie 存储经过加密，因此读取它们意味着需要访问 Keychain，你应该会看到 Keychain 提示。读取的内容是你在所搜索网站上的会话 Cookie，它们会被放入发往同一网站的请求中。所有可能接收 Cookie 的提供方定义都会经过源码审查并嵌入二进制文件；运行时提供方 JSON 不可执行。客房查询中由调用方提供的 URL 会在附加 Cookie 前与 Booking.com 进行校验；如果这一点不再成立，测试就会失败。如果某个网站将 trvl 重定向到另一个主机，Cookie 不会跟随：Go 的 HTTP 客户端会拒绝在主机变更时携带 Cookie。此检查比较的是主机，而非协议，因此如果网站将自己的 https:// 地址重定向到纯 http://，Cookie 仍会保留——网站将自己的流量降级为明文，是唯一会导致会话未加密地通过网络传输的情况。trvl 不会向自己的任何端点报告你的 Cookie。

可选的提供方定义仅包含在源码中。 trvl providers enable <id> 只能启用当前二进制文件中随附且经过审查的定义。运行时状态文件会记录用户同意、启用状态和运行状况；它无法替换端点、标头、身份验证、请求模板或响应映射。~/.trvl/providers 下的旧文件会保留，以便回滚或手动迁移，但 trvl 不会加载它们。新定义必须通过经过审查的源码变更（或用户维护的分支）提供。

它会在 ~/.trvl 下保存工作状态： 已保存的行程、偏好设置和旅客资料、价格提醒、搜索历史、缓存的 Cookie 和提供方令牌、提供方运行状况日志、Google 速率限制冷却状态、升级和提供方自我修复记录，以及随机生成的安装 ID。此状态仅保存在本地。发布版本每天最多会向 https://telemetry.revaluator.ai/v1/heartbeat 发送一次安装 ID，不会发送此目录中的其他内容。TRVL_TELEMETRY_ENDPOINT 可以替换该 URL。TRVL_NO_TELEMETRY=1 会停止发送。如果你为价格提醒提供了 webhook URL，trvl 会向你提供的地址 POST 该提醒的路线和价格数据，这正是 webhook 的用途。

JSON 状态文件会先写入临时文件，然后重命名并覆盖目标文件，因此崩溃不会留下只写了一半的 JSON 文档。价格提醒及其历史记录使用事务式 watch.db 存储；首次迁移会先备份旧版 JSON，再提交数据库。临时文件替换仍可能留下因写入中断而产生的孤立临时文件，每个文件都是原本要替换的 JSON 文件的完整副本。trvl 不会自行删除这些文件，因为孤立文件有时是目标文件仅存的副本。trvl tempfiles 会报告这些文件及其大小和存在时间；trvl tempfiles --delete 只会删除已确认写入进程不再运行的文件。

你可以选择拒绝上述任一行为：

export TRVL_NO_BROWSER_COOKIES=1   # never read your browsers or the sessions in them, and never open a window in your real browser
export TRVL_NO_TIER2_CDP=1         # never start a headless browser of its own

这两个开关都以覆盖范围换取隔离性。默认启用 Cookie 访问，因为受保护的酒店和铁路信息源依赖现有会话；关闭后，搜索结果可能会明显减少。只有在受挑战的信息源需要新 Cookie 时，无头模式备用方案才会启动已安装的 Chrome、Brave 或 Edge，并使用空白配置文件。它不会读取你现有的浏览器会话、显示窗口或抢占焦点。关闭后，受挑战的信息源可能无法返回结果。少数服务提供商另有可见浏览器恢复流程，但该流程彼此独立、因服务提供商而异，并且会在打开前征求许可；关闭无头模式备用方案不会自动启用该流程。

如果你使用代理

trvl 遵循 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。它会检查并固定两跳连接——代理和目标地址——因此，重定向或 DNS 解析结果变更都无法将连接引向 URL 中从未指定的地址。

默认情况下，trvl 拒绝连接到私有、环回和链路本地地址，从而防止恶意重定向访问你的内部网络或云元数据端点。企业代理几乎总是使用私有地址，因此要连接此类代理，必须明确选择启用：

export TRVL_ALLOW_PRIVATE_PROXY=1   # the PROXY may be on a private address

这只会放宽对代理这一跳的限制。目标地址仍会因使用私有地址而被拒绝。范围更广的 TRVL_ALLOW_LOCAL_PROVIDERS=1 会同时允许代理和目标地址，并用于让 trvl 连接到你本机上的模拟服务提供商——不要仅仅为了使用代理就启用它，因为它也会关闭目标地址防护。

不支持经过身份验证的代理（http://user:pass@host）。

如果你在云服务器上运行 trvl

trvl 会直接调用旅游网站，而其中许多网站会将云和数据中心 IP 地址视为机器人。从服务器发起相同搜索时，返回的选项可能比在家中少。trvl 会报告这一情况，而不会隐瞒。provider_statuses 中的每个服务提供商都会在未能响应时附带一个 reason：blocked（请求被拒绝，通常是 HTTP 403 或机器人检查）、rate_limited、unavailable（服务提供商自身返回 5xx 错误）、dns、network 或 timeout。部分服务提供商失败的搜索会标记为 partial，而不会标记为“未找到任何结果”。

一位用户在 2026 年 10 月从 Kubernetes 集群进行了测量：SNCF、Trainline 和 Rome2Rio 返回 403，Wizz Air 返回 503，而 Italo 的主机在某些 DNS 解析器上无法解析。只有 403 表明 IP 受到屏蔽；503 或 DNS 故障也可能由其他原因导致。使用家庭或办公室网络连接，或采用上文所述的代理支持，通常可以改善覆盖范围，但无法保证一定有效。

trvl 保留多少价格历史记录

价格监控仍处于实验阶段。 它可以正常运行，也会保留数据——你的监控项及其完整价格历史记录都存放在 ~/.trvl 下。请把这些历史记录视为可能丢失的数据。迁移前会备份存储，迁移后也会保留旧文件，因此即使出现问题也能恢复；但这项功能比 trvl 的其他部分推出得更晚，变动也更频繁。

升级到 1.21.0 可能会删除价格历史记录。 首次运行时会将存储转换为事务型数据库；如果你降低了 TRVL_WATCH_MAX_POINTS_PER_WATCH，转换时现在会遵守该限制。此前的版本在其他场景中会应用此限制，但转换时会忽略它，因此降低后的限制实际上并未生效。超过限制的点数会被删除。请先运行 trvl watch migrate --dry-run，查看实际数量：预览此前会低估数量，因此才有这条警告。

监控价格历史记录有上限；否则它会无限增长。某个实际存储曾达到 320,028 个点，占用 41MB，导致每个运行中的 trvl 进程都使用约 686MB 内存。三个限制共同控制其规模，并且都可以更改。

export TRVL_WATCH_MAX_POINTS_PER_WATCH=1000   # points kept per watch
export TRVL_WATCH_MAX_POINTS_TOTAL=50000      # points kept across all watches
export TRVL_WATCH_ROUTE_TTL_DAYS=90           # how long a dateless route watch keeps being checked

以下为默认值，以及调整每项限制的代价：

无效值会被拒绝，而非调整：如果 TRVL_WATCH_MAX_POINTS_TOTAL=0，trvl 将无法启动，而不会悄悄改用默认值，让你误以为设置已生效。

若要查看哪些限制正在影响你的存储，请运行 trvl watch migrate --dry-run。它会报告磁盘占用、每个监控项的点数分布，以及各项限制的使用情况，且不会更改任何内容。

完整机制——各项内容的读取时机、这两个开关之间的确切差异、无头浏览器回退方案，以及 AF-KLM 凭据规则：请参阅 docs/ARCHITECTURE.md。

有一条命令会主动发布内容，因为这正是你运行它的目的：日历助手会向你的 Google 日历中添加事件。trvl share 不会发布内容——它会打印行程卡片，或将其复制到剪贴板，由你决定分享给谁。它过去会将卡片上传为公开的 GitHub gist；后来在 #527 中移除了此功能，因为卡片包含目的地和日期，而这些信息会透露你家中无人时的时间。

可选的凭据提供方

trvl 默认使用的所有数据源都是免费的，无需账号。只有在你提供自己的密钥时，这些额外功能才会启用；否则不会产生任何影响：

所有这些密钥都会从环境中读取。AF-KLM 是唯一的例外，但仅在你主动要求时：显式指定 --provider afklm 后，它还可以从 macOS 钥匙串或 1Password 读取密钥。普通搜索不会访问此表中的任何凭据管理器——相关说明请见 docs/ARCHITECTURE.md。

隐私与遥测

已发布的构建每天最多向 https://telemetry.revaluator.ai/v1/heartbeat 发送一次心跳。设置 TRVL_TELEMETRY_ENDPOINT，即可将相同的请求正文发送到其他位置。请求正文仅包含：

• 固定的项目标签（trvl）和事件名称（heartbeat）
• trvl 版本
• Go 运行时字符串（操作系统、架构、Go 版本，例如 darwin/arm64/go1.26.9）
• 随机安装 ID，在首次发送此类请求时创建，并存储在 ~/.trvl/install-id

不包含主机名、用户名、搜索查询或旅行数据。JSON 请求正文不包含你的 IP 地址。默认主机的 TLS 由 Cloudflare 终止，因此 Cloudflare 可以看到连接地址。接收方不会记录该地址。根据连接信息，Cloudflare 的地理定位服务会提供城市名称和国家代码，这两个值会与心跳一起存储。这些信息是近似值：VPN、中继或移动网络可能会将城市定位到网络出口位置，而非你所在的位置；有些连接则没有城市信息。坐标和请求标头不会被存储。安装 ID 每天保持不变，因此这些请求可以相互关联，包括与它们一起存储的城市信息。该 ID 是随机生成的，不包含任何关于你的信息。请求超时时间为 3 秒，请求失败会被忽略。

开发构建（go build / go run，版本为 dev）、CI 和测试不会发送遥测数据。要关闭遥测，请在运行 trvl 前设置以下任意一项：

export TRVL_NO_TELEMETRY=1   # trvl-specific switch
export NO_TELEMETRY=1        # common convention
export DO_NOT_TRACK=1        # cross-tool Do-Not-Track signal

将其作为 HTTP／远程服务运行

本地 stdio 是默认且最安全的传输方式。trvl mcp --http 会绑定到 127.0.0.1，要求提供 bearer token，并会在未设置时于启动时生成一个。远程访问、范围受限的读／写令牌以及 OAuth 2.1 内省：docs/REMOTE-MCP-OAUTH.md。

故障排查

• 没有显示工具？ 执行 trvl mcp install 后重启 AI 客户端；确认 which trvl 位于 $PATH 中。
• 航班搜索结果为空？ 有些航线没有 Google Flights 数据；试试主要航线组合，例如 trvl flights HEL LHR 2027-07-01。
• 地面交通请求超时？ 铁路／渡轮提供方会进行限流；30 秒后重试，或传入 --timeout 3m。

完整的故障排查指南：docs/CLI.md。

可在以下平台获取

Glama · LobeHub · Smithery · MCPHub · Cursor Directory · PulseMCP · MCP Market · pkg.go.dev

第三方目录会缓存各自的描述，显示的工具或命令数量可能较旧。有关当前功能和发布版本，请参阅本 README、更新日志和官方 MCP Registry。

独立评测： Roberto Reale 的预算旅行工作流——一项独立的构建与测试，发现了实际问题，并影响了 v1.10 信任路线图。

生态系统

属于一套 MCP 工具的一部分：mcp-gateway（通用网关） · nab（带反机器人功能的网页提取） · axterminator（macOS GUI 自动化）。

法律与许可证

trvl 是一款个人用途工具，用于读取面向公众的 Web API（Google Flights、Google Hotels 等）。它不会绕过身份验证或规避速率限制；请求模式会受到限制，以模拟手动浏览。自动访问可能违反某些服务提供商的服务条款——您有责任遵守所在司法辖区的规定。

trvl flights 和 trvl hotels 接受可选的 --stealth 标志，该标志会通过 trvl 的 Chrome HTTP/2 指纹传输路由抓取请求。除非您传入该标志，否则此功能默认关闭；它仅对您列入 TRVL_STEALTH_ALLOWLIST 的主机生效；对于不在列表中的主机，它只会记录一行日志，不执行其他操作——允许列表为空时，该功能永远不会启用。只有航班和酒店搜索会遵循此设置。若针对条款禁止自动访问的网站使用隐身功能，责任由您承担。

export TRVL_STEALTH_ALLOWLIST=".google.com"
trvl flights HEL NRT 2027-09-01 --stealth

采用 PolyForm Noncommercial 1.0 许可证——可免费用于个人及非商业用途。商业用途（公司内部使用、托管服务、嵌入付费平台）需要单独许可：每个指定项目每月 EUR 500，可通过 GitHub Sponsors 支付；详见 COMMERCIAL.md 和 LICENSING.md。

基于 fli、utls 以及 SerpAPI 的参数参考构建。

给它点个星

如果 trvl 帮您省下了一个浏览器标签页或一份 API 订阅，点个星就能帮助其他旅行者（及其助手）发现它。这就是全部请求。