Aviasales Flight Prices

aviasales-mcp

Aviasales／Travelpayouts Data API を通じて航空券の価格を検索する MCP サーバーです。 Claude Code、Claude Desktop、Cursor、その他の MCP クライアントが航空券の価格に関する質問に答えられるようにする、読み取り専用のツールが 13 個あります。路線や月ごとの運賃、最も安く飛べる日、日程の柔軟な検索、予算や行き先からの検索に加え、空港・都市・航空会社の検索にも対応しています。

Google Flights のスクレイピングを使う MCP サーバーとは異なり、モデルが地名から IATA コードを推測する必要はありません。lookup_cities と find_nearest_airports が地名を解決します。

プロンプトの例

自然な言葉で質問してください。サーバーがツールを選択します。

• 3 月のモスクワからイスタンブールへの航空券はいくらですか？
• 9 月にバンコクへ飛ぶ場合、最も安い日はいつですか？
• 5 月 12 日にベルリンからリスボンへ飛び、19 日に戻ります。前後 1 日ずらすと安くなりますか？
• サンクトペテルブルクから 30,000 ルーブル未満で行ける場所はどこですか？
• パタヤへ行くにはどの空港を利用すればよいですか？また、ドバイからの料金はいくらですか？

よくあるプロンプト

典型的なエージェントが使うツールを含む、同じ種類の質問です。

プロンプト	使用するツール
「3 月のモスクワからイスタンブールへの航空券はいくらですか？」	lookup_cities → search_flights
「9 月にバンコクへ飛ぶ場合、最も安い日はいつですか？」	get_prices_calendar
「5 月 12 日にベルリンからリスボンへ飛び、19 日に戻ります。前後 1 日ずらすと安くなりますか？」	get_flexible_date_prices
「サンクトペテルブルクから 30,000 ₽ 未満で行ける場所はどこですか？」	get_city_directions、search_by_price_range
「パタヤへ行くにはどの空港を利用すればよいですか？また、ドバイからの料金はいくらですか？」	find_nearest_airports → search_flights
「夕方出発のみ、大人 2 名と子ども 1 名、ビジネスクラス。」	depart_after、adults、children、trip_class を指定した search_flights

インストール

これをターミナルに貼り付けてください。以下の各クライアント設定で実行するものと同じ docker コマンドです。プロセスは標準入力で 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 から取得できます。誤ったトークンでもプロセスは起動しますが、最初の検索時にエラーとして表示されます。 AVIASALES_MARKET は任意です。詳しくは設定をご覧ください。不要な場合は、この変数と対応する -e の組み合わせを削除してください。

:latest はリリースに追従します。手動でアップグレードしたい場合は、バージョンタグ（:0.5.2）を指定してください。パッケージはまだ PyPI に公開されていません。リリースワークフローは準備できており、最初のアップロードはメンテナーが PyPI にプロジェクトを登録するのを待っています。それまでは uvx aviasales-mcp では見つからないため、上記のコマンドがインストール方法です。

MCP クライアントの設定

各ブロックは、上記のターミナル用スニペットと同じ docker コマンドを実行します。 値を指定しない -e AVIASALES_API_TOKEN は、クライアントが env に設定した変数をコンテナに渡します。これにより、トークンを記述する場所は 1 か所だけになります。

トークンをコミットするファイルに記載しないでください。 プロジェクトレベルの .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（すべてのプロジェクト）または .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 として登録されており、レジストリを参照できるクライアントから直接インストールできます。

検証済みクライアントと OS

実際に実行したものだけを検証済みとしています。それ以外はクライアントのドキュメントに基づいて設定を記述したもので、試していません。

クライアントまたはパス	OS	ステータス	方法
テストスイート、Python 3.12 / 3.13 / 3.14	Linux（GitHub ubuntu-latest）	すべての PR および main へのプッシュで検証済み	ci.yml。HTTP はモック化
Docker ランタイムイメージのビルド	Linux（GitHub ubuntu-latest）	すべての PR および main へのプッシュで検証済み	ci.yml
Docker イメージを使った標準 MCP over stdio（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	未検証
PyPI からの pip install / uvx	任意	未検証	まだ PyPI にはありません

ツール

13 個すべてのツールは読み取り専用で、キャッシュされた運賃と参照データを検索します。予約、購入、書き込み、変更は一切行わず、Travelpayouts のレート制限を除けば呼び出しに料金もかからないため、別途読み取り専用モードを有効にする必要はありません。

航空券の価格

ツール	説明
search_flights	2都市間の指定日または月間の価格（v3/prices_for_dates）
get_prices_calendar	日別または月別にまとめた価格 — 航空券が最も安い日
get_flexible_date_prices	指定日の前後の日の価格 — 「日程を1日ずらすと安くなりますか？」
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 が表示され、実際の合計金額が確認できます。価格自体は常にエコノミークラスの大人1人分です。すべての価格レスポンスに含まれる 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 を指定してください。 基となるデータセットには、空港が約 1 万件、都市が約 9,600 件含まれています。これはどのモデルのコンテキストにも収まりきらないほどの量です。検索結果は関連度順（コードの完全一致、都市コードの完全一致、名前の順）に並び、定期便のない空港は最後に表示されます。各データセットはプロセスごとに一度ダウンロードされ、24 時間キャッシュされます。

find_nearest_airports は、lookup_airports では答えられない質問に対応します。最寄りの空港の名前が町の名前と一致することは、ほとんどありません。キャッシュ済みの都市と空港のデータセットを使って near="Pattaya" を解決し、大圏距離に基づいて並べ替えます。サードパーティのジオコーダーは使用しません。

エラーと空の検索結果

すべてのレスポンスには status（"ok" または "error"）が含まれるため、data リストが空の場合もエラーと混同されません。不正な入力は API 呼び出し前に拒否され、想定される形式が明記されます（"departure_at must be \"YYYY-MM-DD\" or \"YYYY-MM\"…"）。エラーレスポンスと空のレスポンスには、次に試す内容を示す hint も含まれます。引数が拒否された場合、ヒントには置き換える内容と、それを解決するツールが記載されているため、モデルは2回目の試行で呼び出し自体を修正できます。

セットアップ

チェックアウトから自分でイメージをビルドする方法（イメージをプルする代わりに使用）：

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）
MCP_PORT	いいえ	stdio の代わりに、このポートでストリーミング可能な HTTP を提供します（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）

AVIASALES_MARKET の設定をおすすめします。価格キャッシュは市場ごとに異なり、同じ通貨の同じルートでも、ru と us では価格が異なります。

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 も設定しない限り、起動を拒否します。

制限事項

• 価格は直近の検索結果をキャッシュしたものであり、リアルタイムの空席状況ではありません。 リンクを開くまでに運賃がなくなることがあります。expires_at は見積もりの有効期限を示します。
• 価格は常にエコノミークラスの大人 1 名分です。 乗客数と客室クラスは予約リンクに反映されますが、表示価格には反映されません。
• 予約はできません。 このサーバーは検索と外部リンクの提供のみを行い、座席の確保や購入は行いません。
• キャッシュのカバー範囲には偏りがあります。 結果が空でも、そのルートが存在しないのではなく、最近そのルートを検索した人がいないことを意味します。
• 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 テストスイートの後、タグのバージョンとの一致を確認した sdist と wheel の作成、twine check、Trusted Publishing を使用した PyPI へのアップロード（トークンはどこにも保存しません）、そして sdist、wheel、.mcpb、checksums.txt を含む GitHub Release の作成を行います。 registry.yml は同じタグからイメージと MCP レジストリエントリーを公開します。 pyproject.toml と server.json の version はタグと一致している必要があります。

ライセンス

GPL-3.0-or-later — 詳細は LICENSE を参照してください。