aviasales-mcp

# aviasales-mcp

<!-- mcp-name: io.github.stufently/aviasales-mcp -->

MCP server for flight price search via Aviasales / Travelpayouts Data API.
Thirteen read-only tools that let Claude Code, Claude Desktop, Cursor or any
other MCP client answer flight-price questions: fares by route and month, the
cheapest day to fly, flexible dates, budget and inspiration search, plus
airport/city/airline lookup.

Unlike Google-Flights-scraping MCP servers, place names do not have to be
guessed into IATA codes by the model: `lookup_cities` and `find_nearest_airports`
resolve them.

## Example prompts

Ask in plain language. The server picks the tool.

- How much is a flight from Moscow to Istanbul in March?
- What is the cheapest day to fly to Bangkok in September?
- I am flying Berlin to Lisbon on 12 May and back on the 19th. Would shifting a day either way be cheaper?
- Where can I fly from St Petersburg for under 30 000 rubles?
- Which airport should I fly into for Pattaya, and what does it cost from Dubai?

## Common prompts

The same kind of question, with the tools a typical agent reaches for.

| Prompt | Tools it reaches for |
|--------|----------------------|
| "How much is a flight from Moscow to Istanbul in March?" | `lookup_cities` → `search_flights` |
| "What's the cheapest day to fly to Bangkok in September?" | `get_prices_calendar` |
| "I'm flying Berlin→Lisbon on 12 May, back on the 19th — would shifting a day either way be cheaper?" | `get_flexible_date_prices` |
| "Where can I fly from St Petersburg for under 30 000 ₽?" | `get_city_directions`, `search_by_price_range` |
| "Which airport should I fly into for Pattaya, and what does it cost from Dubai?" | `find_nearest_airports` → `search_flights` |
| "Evening departures only, two adults and a child, business class." | `search_flights` with `depart_after`, `adults`, `children`, `trip_class` |

## Install

Paste this into a terminal. It is the same `docker` command every client block
below runs; the process speaks MCP on stdin and waits there.

```bash
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
```

You need Docker, and a free Travelpayouts API token from
<https://www.travelpayouts.com/programs/100/tools/api>. A wrong token still
lets the process start; it surfaces as an error on the first search.
`AVIASALES_MARKET` is optional — see [Configuration](#configuration). Drop
that variable and its `-e` pair if you do not need it.

`:latest` follows releases; pin a version tag (`:0.5.2`) if you would rather
upgrade by hand. The package is not on PyPI yet: the release workflow is
ready, and the first upload waits for the maintainer to register the project on
PyPI. Until then `uvx aviasales-mcp` finds nothing and the command above is the
install path.

## MCP client configs

Every block runs the same `docker` command as the terminal snippet above.
`-e AVIASALES_API_TOKEN` with no value hands the container the variable the
client sets in `env`, so the token is written in exactly one place.

> **Keep the token out of anything you commit.** A project-level `.mcp.json`,
> `.cursor/mcp.json` or `.zed/settings.json` is a normal thing to check into git,
> and a token pasted there goes with it. Prefer the user-level config file, or
> `.gitignore` the project one.

### Claude Code

Project file: `.mcp.json` in the project root.

```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"
      }
    }
  }
}
```

Or from the terminal:

```bash
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` makes it available in every project and keeps the token in
`~/.claude.json`, out of the repository. Check with `claude mcp list`.

### Claude Desktop

File: `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`.

```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"
      }
    }
  }
}
```

One click, without editing JSON: download the `.mcpb` from
https://github.com/stufently/aviasales-mcp/releases/latest and open it.
Claude Desktop installs the extension and asks for the Travelpayouts API token.

The same release includes `checksums.txt`, the SHA256 of every file attached
to it: the `.mcpb`, and from the first PyPI release on also the sdist and the
wheel, byte for byte the files uploaded to PyPI. Download it into the same
directory as the bundle and check it before opening the bundle:

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

On macOS, `shasum -a 256 -c` checks the same file.

Claude Desktop starts with a trimmed `PATH` and may not find `docker` by name: if
the server fails to start, replace `"docker"` with its absolute path
(`which docker`).

### Cursor

File: `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project).

```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

File: `mcp_config.json` — macOS and Linux `~/.config/devin/mcp_config.json`
(or `$XDG_CONFIG_HOME/devin/mcp_config.json`), Windows
`%APPDATA%\devin\mcp_config.json`. Older builds read
`~/.codeium/windsurf/mcp_config.json`.

```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

File: `settings.json` at `~/.config/zed/settings.json` (or **zed: open settings**).

```json
{
  "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

```bash
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
```

Or by hand in `~/.codex/config.toml`:

```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"
```

### Any other stdio client

Command `docker`, arguments
`run -i --rm -e AVIASALES_API_TOKEN ghcr.io/stufently/aviasales-mcp:latest`, and
`AVIASALES_API_TOKEN` in the environment the client gives the process. The
server is also listed in the official MCP registry as
`io.github.stufently/aviasales-mcp`, which clients with a registry browser can
install from directly.

## Verified clients and OS

Only what was actually run is marked verified. Everything else is a config
written from the client's documentation and has not been tried.

| Client or path | OS | Status | How |
|----------------|----|--------|-----|
| Test suite, Python 3.12 / 3.13 / 3.14 | Linux (GitHub `ubuntu-latest`) | Verified on every PR and push to `main` | `ci.yml`; HTTP is mocked |
| Docker runtime image build | Linux (GitHub `ubuntu-latest`) | Verified on every PR and push to `main` | `ci.yml` |
| Plain MCP over stdio (`initialize`, `tools/list`) with the Docker image | Linux x86_64 | Verified 2026-10-12 | 13 tools listed, every one `readOnlyHint: true`, `destructiveHint: false` |
| Claude Code 2.1.296, Docker command from this README | Linux x86_64 | Verified 2026-10-12: connects and lists all 13 tools | A placeholder token; no tool call reached the API in this check |
| `uv run` launch used by the `.mcpb` | Linux, `ghcr.io/astral-sh/uv` image | Verified 2026-10-10: starts and answers `tools/list` | Without Claude Desktop |
| Travelpayouts Data API with a real token | Linux | Verified 2026-07-29 (live probe of the Data API endpoints) | See CHANGELOG |
| Claude Desktop (`.mcpb` or JSON config) | macOS, Windows, Linux | **Not verified** | No Claude Desktop on the test host |
| Cursor, Windsurf, Zed, Codex | any | **Not verified** | Configs follow each client's docs as of 2026-10-10 |
| Any client on macOS or Windows | macOS, Windows | **Not verified** | |
| `pip install` / `uvx` from PyPI | any | **Not verified** | Not on PyPI yet |

## Tools

All thirteen tools only read: they search cached fares and reference data. None
books, buys, writes or changes anything, and none costs money to call beyond
the Travelpayouts rate limit, so there is no separate read-only mode to turn on.

### Flight prices

| Tool | Description |
|------|-------------|
| `search_flights` | Prices between two cities on a d