Skip to main content
Glama
Sign In
air_choose

air_choose

by bitwiresys
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Read-only MCP server that monitors flight prices across multiple airline providers. An AI agent (Hermes, OpenClaw, Claude, etc.) adds, removes, and inspects watched routes through MCP tools; a background scheduler re-checks every watch hourly and queues new/cheaper offers for the agent to pick up. No ticket ordering — only available flight data.

Features

  • Multi-provider — Kupibilet (worldwide), Ryanair (Europe), SpiceJet (India), Jetstar Asia (Asia-Pacific)

  • Flights only — trains and other transport types are filtered out automatically

  • Smart resolution — turn "Moscow → Thailand" into provider-specific airport/country codes

  • Price drop detection — tracks best-ever prices per route, queues notifications when fares drop

  • MCP-native — works with any MCP-compatible agent host

Related MCP server: bhinneka

Quick Start

Local

git clone https://github.com/yourusername/air-choose.git
cd air-choose
npm install
node src/server.js

Docker

docker compose up -d

Wire into your agent

{
  "mcpServers": {
    "air-choose": {
      "command": "node",
      "args": ["/absolute/path/to/air-choose/src/server.js"]
    }
  }
}

Configuration

Env Variable

Default

Description

AIR_CHOOSE_INTERVAL_MS

3600000 (1 hour)

Scheduler re-check interval

Tools

Tool

Purpose

list_providers

See airline providers, coverage, browser requirements

resolve_location

Turn a place name into each provider's own codes

add_watch

Add a route to monitor (resolves + runs first check immediately)

remove_watch

Stop watching a route

list_watches

See everything currently watched

get_watch_offers

Current offers for one watch, sorted by price or date

poll_new_offers

Return + clear everything new since last call

force_check

Re-run a watch's check right now

Providers

Provider

Coverage

Auth

Notes

Kupibilet

Worldwide

No

Accepts ISO2 country codes directly

Ryanair

Europe

No

Can rate-limit (409) under heavy use

SpiceJet

India

Auto token

Calendar view, no exact departure times

Jetstar Asia

Asia-Pacific

Browser session

Excluded by default (Akamai)

Architecture

MCP Client (Hermes / Claude / ...)
        | JSON-RPC (stdio)
air-choose server
  |-- Tools (8)
  |-- Scheduler (hourly)
  |-- Provider Adapters (Kupibilet | Ryanair | SpiceJet | Jetstar)
  |-- JSON Store (watches | offers | pending)

Example Flow

Agent -> resolve_location({ query: "Moscow" })
Agent -> resolve_location({ query: "Thailand" })
Agent -> add_watch({
           originQuery: "Moscow",
           destinationQuery: "Thailand",
           dateFrom: "2026-07-21",
           dateTo: "2026-08-20"
         })
        -> Server resolves, runs check, returns offers sorted by price

... one hour later, scheduler re-checks ...

Agent -> poll_new_offers()
        -> Returns new or cheaper offers found since last poll

Testing

npm test           # unit tests
npm run test:e2e   # end-to-end (hits live APIs)
npm run test:all   # all tests

Legal

Reverse-engineered consumer-facing endpoints, not published partner APIs. Keep the hourly interval reasonable.

License

MIT

Available Tools

8 tools
add_watchAdd a watched routeA

Add a route to monitor. originQuery/destinationQuery go through the same resolution as resolve_location for every requested provider, immediately, and the watch stores each provider’s resolved codes — you get that resolution back in the response so you can sanity-check it before relying on the watch. An immediate first check runs right away (you do not have to wait for the hourly cycle to get initial results) and its offers are returned too.

Inputs: dateTo (required), dateFrom (required), originQuery (required), destinationQuery (required), +4 more.

force_checkForce an immediate checkB

Re-run the fare check for one watch right now, instead of waiting for the hourly cycle.

Inputs: id (required).

get_watch_offersGet current offers for a watchB

Return the latest known offers for a watch, from the most recent check (hourly, or forced).

Inputs: id (required), limit, sortBy.

list_providersList flight/ticket providersA

List every provider air_choose can query, with its coverage region and whether it needs a live browser session (those are NOT included here — only providers that work with plain HTTP calls are).

Inputs: no named parameters.

list_watchesList watched routesA

List every currently watched route, with when it was last checked and how many offers it has.

Inputs: no named parameters.

poll_new_offersPoll for newly found offers (main wake-up tool)A

Return every offer discovered since the last time this was called — new routes/dates appearing, or a price drop below the previously-seen best price — across ALL watches, and clears the queue. This is the reliable way to find out "what changed": call it on your own schedule (e.g. once an hour) rather than relying on push notifications, since not every MCP host wakes an idle agent on server notifications.

Inputs: no named parameters.

remove_watchRemove a watched routeA

Stop monitoring a route and forget its price history.

Inputs: id (required).

resolve_locationResolve a place name to each provider’s own codesA

Every provider uses its own internal airport/city/country codes — you cannot just pass a Russian or English place name straight into a search. Call this FIRST for both the origin and the destination before add_watch, so you can see what each provider actually understood the place as. Accepts a country name (RU or EN, e.g. "Таиланд" / "Thailand"), a 3-letter IATA code (e.g. "BKK"), or a handful of built-in city aliases (Moscow, London, Singapore, Delhi, ...). Returns, per provider, the list of matched airports/cities/country codes — an empty list for a provider means that provider does not serve that place at all (e.g. Ryanair has no Moscow routes), which is normal, not an error.

Inputs: query (required), providers.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct action: add_watch, force_check, get_watch_offers, list_watches, remove_watch all operate on watches but with different operations; list_providers, poll_new_offers, and resolve_location are entirely separate concerns. No overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_watch, list_providers, resolve_location). The naming is predictable and clear throughout.

    Tool Count5/5

    8 tools is appropriate for an airfare monitoring server. It covers all necessary operations without being bloated or too sparse.

    Completeness4/5

    The toolset covers the full lifecycle of watch management (create, read, delete, force check) plus location resolution and provider listing. A minor gap is the lack of an update watch functionality, but this is not critical for the core use case.

    Resources

    Related MCP Connectors

    Related MCP Servers