Aviasales Flight Prices

aviasales-mcp

用于通过 Aviasales / Travelpayouts Data API 搜索机票价格的 MCP 服务。 提供 13 个只读工具，让 Claude Code、Claude Desktop、Cursor 或任何其他 MCP 客户端回答机票价格相关问题：按航线和月份查询票价、查找最便宜的出行日期、灵活日期搜索、预算和灵感搜索，以及机场／城市／航空公司查询。

与通过抓取 Google Flights 数据的 MCP 服务不同，模型不必猜测地名对应的 IATA 代码：lookup_cities 和 find_nearest_airports 可以解析地名。

示例提示词

用自然语言提问。服务会选择合适的工具。

• 3 月从莫斯科飞往伊斯坦布尔的机票多少钱？
• 9 月飞往曼谷哪一天最便宜？
• 我将于 5 月 12 日从柏林飞往里斯本，19 日返程。如果前后调整一天，票价会更便宜吗？
• 从圣彼得堡出发，3 万卢布以内可以飞到哪里？
• 飞往芭提雅应该选择哪个机场？从迪拜出发的票价是多少？

常见提示词

典型 Agent 会用这些工具处理的同类问题。

提示词	会用到的工具
“3 月从莫斯科飞往伊斯坦布尔的机票多少钱？”	lookup_cities → search_flights
“9 月飞往曼谷哪一天最便宜？”	get_prices_calendar
“我将于 5 月 12 日从柏林飞往里斯本，19 日返程——前后调整一天会更便宜吗？”	get_flexible_date_prices
“从圣彼得堡出发，3 万 ₽ 以内可以飞到哪里？”	get_city_directions、search_by_price_range
“飞往芭提雅应该选择哪个机场？从迪拜出发的票价是多少？”	find_nearest_airports → search_flights
“只选晚间出发，两位成人和一位儿童，商务舱。”	使用 depart_after、adults、children、trip_class 调用 search_flights

安装

将以下内容粘贴到终端中。下面每个客户端配置块运行的都是同一条 docker 命令；该进程通过 stdin 使用 MCP 通信，并等待输入。

AVIASALES_API_TOKEN=your-token-here AVIASALES_MARKET=ru \
  docker run -i --rm \
  -e AVIASALES_API_TOKEN \
  -e AVIASALES_MARKET \
  ghcr.io/stufently/aviasales-mcp:latest

你需要安装 Docker，并获取免费的 Travelpayouts API 令牌：https://www.travelpayouts.com/programs/100/tools/api。即使令牌无效，进程仍会启动（Docker 镜像中不提供令牌时也一样）；首次搜索时才会报错。 AVIASALES_MARKET 是可选项——参见配置。如果不需要，请移除该变量及其对应的 -e 参数。

:latest 会随版本发布更新；如果希望手动升级，请固定使用版本标签（:0.5.3）。

不使用 Docker 时，也可以通过 PyPI 安装同一服务（Python 3.12+）：aviasales-mcp。 uvx 可以一步完成获取和运行：

AVIASALES_API_TOKEN=your-token-here AVIASALES_MARKET=ru uvx aviasales-mcp

运行 pip install aviasales-mcp 会将同一个 aviasales-mcp 命令添加到 PATH。在客户端配置中，使用 "command": "uvx", "args": ["aviasales-mcp"]，并在 env 中设置令牌，以此替代下面配置块中的 docker 命令。

MCP 客户端配置

每个配置块运行的 docker 命令都与上面的终端示例相同。 不带值的 -e AVIASALES_API_TOKEN 会将客户端在 env 中设置的变量传递给容器，因此令牌只需写在一个位置。

不要将令牌放入任何会提交的文件中。 项目级的 .mcp.json、 .cursor/mcp.json 或 .zed/settings.json 都可能被正常提交到 git， 粘贴在其中的令牌也会一并提交。建议使用用户级配置文件，或将项目配置文件加入 .gitignore。

Claude Code

项目配置文件：项目根目录下的 .mcp.json。

{
  "mcpServers": {
    "aviasales": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AVIASALES_API_TOKEN",
        "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"
      ],
      "env": {
        "AVIASALES_API_TOKEN": "your-token-here",
        "AVIASALES_MARKET": "ru"
      }
    }
  }
}

或者在终端中运行：

claude mcp add --scope user aviasales \
  -e AVIASALES_API_TOKEN=your-token-here -e AVIASALES_MARKET=ru -- \
  docker run -i --rm -e AVIASALES_API_TOKEN -e AVIASALES_MARKET \
  ghcr.io/stufently/aviasales-mcp:latest

--scope user 会让该配置在所有项目中生效，并将令牌保存在 ~/.claude.json 中，避免令牌进入代码仓库。运行 claude mcp list 进行检查。

Claude Desktop

文件：claude_desktop_config.json — macOS ~/Library/Application Support/Claude/claude_desktop_config.json，Windows %APPDATA%\Claude\claude_desktop_config.json，Linux ~/.config/Claude/claude_desktop_config.json。

{
  "mcpServers": {
    "aviasales": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AVIASALES_API_TOKEN",
        "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"
      ],
      "env": {
        "AVIASALES_API_TOKEN": "your-token-here",
        "AVIASALES_MARKET": "ru"
      }
    }
  }
}

一键安装，无需编辑 JSON：从 https://github.com/stufently/aviasales-mcp/releases/latest 下载 .mcpb 并打开。 Claude Desktop 会安装扩展，并提示输入 Travelpayouts API 令牌。

同一版本发布还包含 checksums.txt，其中列出了附加到该版本的每个文件的 SHA256：.mcpb，以及从首个 PyPI 版本开始提供的 sdist 和 wheel；这些校验和与上传到 PyPI 的文件逐字节一致。将其下载到与扩展包相同的目录，并在打开扩展包前进行校验：

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded files

在 macOS 上，shasum -a 256 -c 可校验同一文件。

Claude Desktop 启动时使用精简版 PATH，可能无法通过名称找到 docker：如果服务无法启动，请将 "docker" 替换为其绝对路径（which docker）。

Cursor

安装后，在 ~/.cursor/mcp.json 中将 your-token-here 替换为你的令牌。也可以手动添加以下配置块。

文件：~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（当前项目）。

{
  "mcpServers": {
    "aviasales": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AVIASALES_API_TOKEN",
        "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"
      ],
      "env": {
        "AVIASALES_API_TOKEN": "your-token-here",
        "AVIASALES_MARKET": "ru"
      }
    }
  }
}

Windsurf

文件：mcp_config.json — macOS 和 Linux：~/.config/devin/mcp_config.json （或 $XDG_CONFIG_HOME/devin/mcp_config.json），Windows： %APPDATA%\devin\mcp_config.json。较旧版本会读取 ~/.codeium/windsurf/mcp_config.json。

{
  "mcpServers": {
    "aviasales": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AVIASALES_API_TOKEN",
        "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"
      ],
      "env": {
        "AVIASALES_API_TOKEN": "your-token-here",
        "AVIASALES_MARKET": "ru"
      }
    }
  }
}

Zed

文件：~/.config/zed/settings.json 中的 settings.json（或 zed: open settings）。

{
  "context_servers": {
    "aviasales": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AVIASALES_API_TOKEN",
        "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"
      ],
      "env": {
        "AVIASALES_API_TOKEN": "your-token-here",
        "AVIASALES_MARKET": "ru"
      }
    }
  }
}

Codex

codex mcp add aviasales --env AVIASALES_API_TOKEN=your-token-here -- \
  docker run -i --rm -e AVIASALES_API_TOKEN ghcr.io/stufently/aviasales-mcp:latest

或者在 ~/.codex/config.toml 中手动配置：

[mcp_servers.aviasales]
command = "docker"
args = ["run", "-i", "--rm", "-e", "AVIASALES_API_TOKEN", "-e", "AVIASALES_MARKET",
        "ghcr.io/stufently/aviasales-mcp:latest"]

[mcp_servers.aviasales.env]
AVIASALES_API_TOKEN = "your-token-here"
AVIASALES_MARKET = "ru"

任何其他 stdio 客户端

命令为 docker，参数为 run -i --rm -e AVIASALES_API_TOKEN ghcr.io/stufently/aviasales-mcp:latest，并在客户端提供给进程的环境中设置 AVIASALES_API_TOKEN。该服务也已列入官方 MCP 注册表，名称为 io.github.stufently/aviasales-mcp，可由带有注册表浏览器的客户端直接安装。

已验证的客户端和操作系统

只有实际运行过的项目才标记为已验证。其他内容均根据客户端文档编写了配置，尚未试用。

客户端或路径	操作系统	状态	方式
测试套件，Python 3.12 / 3.13 / 3.14	Linux（GitHub ubuntu-latest）	每次向 main 提交 PR 和推送时均已验证	ci.yml；HTTP 已模拟
Docker 运行时镜像构建	Linux（GitHub ubuntu-latest）	每次向 main 提交 PR 和推送时均已验证	ci.yml
使用 Docker 镜像，通过 stdio 运行纯 MCP（initialize、tools/list）	Linux x86_64	已于 2026-10-12 验证	列出 13 个工具，所有工具均为 readOnlyHint: true、destructiveHint: false
Claude Code 2.1.296，使用本 README 中的 Docker 命令	Linux x86_64	已于 2026-10-12 验证：可连接并列出全部 13 个工具	使用占位令牌；此次检查中没有工具调用触达 API
.mcpb 使用的 uv run 启动方式	Linux，ghcr.io/astral-sh/uv 镜像	已于 2026-10-10 验证：可启动并响应 tools/list	未使用 Claude Desktop
使用真实令牌的 Travelpayouts Data API	Linux	已于 2026-07-29 验证（对 Data API 端点进行了实时探测）	参见 CHANGELOG
Claude Desktop（.mcpb 或 JSON 配置）	macOS、Windows、Linux	未验证	测试主机上没有 Claude Desktop
Cursor、Windsurf、Zed、Codex	任意	未验证	配置依据各客户端截至 2026-10-10 的文档编写
macOS 或 Windows 上的任何客户端	macOS、Windows	未验证
通过 stdio 从 PyPI 运行 uvx [email protected]（initialize、tools/list）	Linux，ghcr.io/astral-sh/uv 镜像	已于 2026-10-14 验证：列出了 13 个工具	使用占位令牌；没有工具调用触达 API

工具

全部 13 个工具都只读取数据：它们搜索缓存票价和参考数据。它们不会预订、购买、写入或更改任何内容；除 Travelpayouts 速率限制外，调用也不产生费用，因此无需单独启用只读模式。

机票价格

工具	描述
search_flights	查询两个城市之间某个日期或整个月的价格（v3/prices_for_dates）
get_prices_calendar	按日或按月汇总价格——找出最便宜的出行日
get_flexible_date_prices	查询您日期前后的价格——“把日期挪动一天会不会更便宜？”
get_latest_prices	查询最近发现的票价，可按航线筛选
get_popular_directions	查询旅客从哪些地方抵达某个目的地
get_city_directions	查询从某个城市可抵达的最便宜目的地——灵感搜索
get_alternative_directions	查询附近机场或城市的价格
search_by_price_range	查询预算范围内的航班；省略目的地即可搜索所有地点（不支持日期筛选——该端点会忽略日期）

search_flights、get_prices_calendar、get_flexible_date_prices 和 get_latest_prices 接受 adults（1–9）、children（0–8）、infants（0–8）和 trip_class（economy/comfort/business/first）。

Data API 提供近期搜索的缓存数据，不接受乘客人数参数，因此同行人数和舱位信息会编码进每张机票的 booking_link 中——该链接会打开 Aviasales，其中已预填完整的同行人数和舱位，并显示实际总价。票价本身始终按经济舱成人票计算，每个价格响应中的 price_note 字段都会向模型说明这一点。

search_flights 还接受 depart_after / depart_before（24 小时制的 HH:MM），用于筛选特定时间段内起飞的航班；若要筛选跨午夜的时间段（红眼航班），请将 depart_after 设为晚于 depart_before。

机票包含 duration_total（门到门总分钟数）、duration_to / duration_back（去程和返程各自的飞行时间）以及 layover_minutes（中转间隙的地面停留总时间）。每个价格响应还包含 price_summary（最低价/中位价/最高价），方便模型无需再次搜索即可判断票价高低。

参考数据

工具	说明
lookup_airlines	按名称或 IATA 代码查找航空公司
lookup_airports	按名称、IATA 代码或城市代码查找机场
lookup_cities	按名称或 IATA 代码查找城市——将城市名称转换为代码
lookup_countries	按名称或代码查找国家
find_nearest_airports	按距离查找离某个地点或经纬度最近的机场

lookup_* 工具接受 search、limit（默认值为 50，最大值为 500）和 locale， 并返回 {status, total, returned, truncated, data}。务必传入 search： 底层数据集约有 10k 个机场和 9.6k 个城市，远超任何模型能放入上下文的数量。 匹配结果会按相关性排序（精确代码、精确城市代码，然后是名称），没有定期航班的机场排在最后。每个数据集在每个进程中下载一次，并缓存 24 小时。

find_nearest_airports 可以回答 lookup_airports 无法回答的问题：最近的机场很少以所在城镇命名。它会根据缓存的城市和机场数据集解析 near="Pattaya"，并按大圆距离排序——不涉及第三方地理编码器。

错误和空结果

每个响应都包含 status（"ok" 或 "error"），因此不会把空的 data 列表误认为失败。API 调用前会拒绝无效输入，并明确说明预期格式（"departure_at must be \"YYYY-MM-DD\" or \"YYYY-MM\"…"）；错误响应和空结果响应都会包含一个 hint，说明接下来可以尝试什么。参数被拒绝时，提示会说明要替换成什么，以及哪个工具可以解析它——足以让模型在第二次尝试时自行修正调用。

设置

从检出代码构建镜像，而不是拉取镜像：

1. 在 https://www.travelpayouts.com/programs/100/tools/api 获取 API 令牌
2. 将 .env.example 复制为 .env，并填入令牌
3. 使用 Docker 构建并运行：

docker build -t aviasales-mcp .
docker run --env-file .env aviasales-mcp

配置

变量	必填	说明
AVIASALES_API_TOKEN	是	Travelpayouts API 令牌
AVIASALES_PARTNER_ID	否	用于预订链接的合作伙伴 ID
AVIASALES_DEFAULT_CURRENCY	否	默认价格货币（默认值：rub）
AVIASALES_MARKET	否	要读取其价格缓存的 2 位市场代码（未设置时 → ru）
AVIASALES_LOCALE	否	参考数据名称的语言（默认值：en）
LOG_LEVEL	否	日志级别（默认值：INFO）
AVIASALES_ENV_FILE	否	要读取的 dotenv 文件路径。未设置时，不会读取 .env（见下文）
MCP_PORT	否	在此端口提供 streamable-HTTP 服务，而不是使用 stdio（也接受 PORT）
MCP_HOST	否	HTTP 模式的绑定地址（默认值：127.0.0.1；在 Docker 中使用 0.0.0.0）
MCP_AUTH_TOKEN	否	每个 HTTP 请求都必须提供的共享密钥
MCP_AUTH_ALLOW_QUERY_TOKEN	否	也接受作为 ?token= 传入的令牌（默认值：false）
MCP_ALLOW_INSECURE_HTTP	否	允许绑定非环回地址且不设置令牌（默认值：false）
MCP_ALLOWED_HOSTS	否	HTTP 传输要响应的主机名，以逗号分隔

建议设置 AVIASALES_MARKET：价格缓存按市场区分，同一条航线使用同一种货币，在 ru 和 us 市场返回的价格会不同。

设置从进程环境中读取。不会读取工作目录中的 .env：MCP 客户端会以打开的项目作为工作目录启动 stdio 服务，其中陌生人的 .env 可能会更改合作伙伴 ID 或传输方式。若要使用 dotenv 文件，请指定其名称：AVIASALES_ENV_FILE=/path/to/.env。 （docker run --env-file .env 不受影响——读取该文件的是 Docker，而不是服务端。）

HTTP 传输

默认情况下，服务使用 stdio 通信，这是本地 MCP 客户端所需的方式。 设置 MCP_PORT 后，会切换为可流式传输的 HTTP，以便远程访问：

docker run --env-file .env \
  -e MCP_PORT=8080 -e MCP_HOST=0.0.0.0 -e MCP_AUTH_TOKEN=<your-secret> \
  -p 8080:8080 aviasales-mcp

此时，端点为 http://<host>:8080/mcp，每个请求都必须通过 Authorization: Bearer <token> 提供令牌；其他请求都会收到 401。

有些 MCP 客户端无法设置请求头。MCP_AUTH_ALLOW_QUERY_TOKEN=true 还会接受 ?token=<token>，但请注意，uvicorn 及其前置的任何代理都会将完整 URL 写入访问日志， 因此密钥会出现在日志中。建议使用请求头。

此处未配置 TLS：如果端口可从不可信的网络访问，请在反向代理处终止 TLS。

如果未设置 MCP_AUTH_TOKEN，该端口将不进行身份验证，任何能够访问它的人都可以消耗你的 Travelpayouts 配额。允许绑定到环回地址（但会发出警告）；绑定到其他地址则会拒绝启动，除非同时设置 MCP_ALLOW_INSECURE_HTTP=true。

系统会检查 Host 和 Origin 请求头，防止网页通过将其 DNS 名称重新绑定到 127.0.0.1 来访问环回服务。绑定到环回地址时，服务会响应 127.0.0.1、localhost 和 ::1；如需添加反向代理的公开名称，请将其加入 MCP_ALLOWED_HOSTS。绑定到其他地址时，服务会响应 MCP_ALLOWED_HOSTS 中的名称；如果位于名称不受你控制的代理后方，请不要设置此变量，此时只有携带 Origin 请求头的请求（浏览器请求）会被拒绝。

限制

• 价格是近期搜索结果的缓存，并非实时余票。打开链接时，票价可能已失效；expires_at 表示报价的失效时间。
• 价格始终按经济舱成人票计算。 乘客人数和舱位会影响预订链接，但不会改变报价。
• 不能预订。 此服务只负责搜索和提供跳转链接，不会锁定或购买机票。
• 缓存覆盖不均。 结果为空表示近期没有人搜索该航线，并不代表该航线不存在。
• get_latest_prices、矩阵和附近机场数据来自较旧的 v2 响应格式：它们提供的是销售方 agency，而非航空公司，且不包含航班号。
• 速率限制按端点计算（大多数端点为 600 次/分钟，周矩阵和附近机场矩阵为 60 次/分钟）。服务会在收到 429 响应时重试，并在公布的配额即将耗尽时发出警告。

开发

docker build --target dev -t aviasales-mcp-dev .
docker run --rm aviasales-mcp-dev pytest -q
docker run --rm -v "$(pwd)":/app -w /app aviasales-mcp-dev ruff check src/ tests/

CI 会在 Python 3.12、3.13 和 3.14 上运行测试套件，并构建 Docker 镜像 — 详见 .github/workflows/ci.yml。

发布

推送 v* 标签会运行 .github/workflows/release.yml：先运行 CI 测试套件，再生成与标签版本匹配且通过 twine check 检查的 sdist 和 wheel，通过 Trusted Publishing 上传到 PyPI（不在任何地方存储令牌），最后创建包含 sdist、wheel、.mcpb 和 checksums.txt 的 GitHub Release。 registry.yml 会根据同一标签发布镜像和 MCP 注册表条目。 pyproject.toml 和 server.json 中的 version 必须与标签一致。

许可证

GPL-3.0-or-later — 详见 LICENSE。