io.github.dimabalony/whentofly
whentofly: flexible-date economy/business flight search + price-level context for AI agents
Open source Repository Open in the app JSON README (API)
About
whentofly: flexible-date economy/business flight search + price-level context for AI agents
Details
- Kind
- MCP servers
- Topic
- Maps, weather & travel
- Publisher
- dimabalony
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.3
- Stars
- 3
- Last push
- 2026-08-26T13:19:20Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-29 03:02:42
- Updated
- 2026-08-29 03:02:42
- Origin id
io.github.dimabalony/whentofly
README
# whentofly — flight search for AI agents (MCP)
**[whentofly.io](https://whentofly.io)** is a flexible-date flight search your AI agent can
use directly. Ask your agent *"cheapest round trip from Singapore to Tokyo in October,
5–9 days"* — it searches a whole date window, returns the cheapest real fares with booking
links, and tells you **where that price sits** against the route's usual range.
No API key. No signup. Two tools, hosted remotely — nothing to run locally.
## Install
**Claude Code**
```bash
claude mcp add whentofly https://whentofly.io/mcp?ch=github
```
**Claude Desktop / claude.ai** — Settings → Connectors → *Add custom connector* →
`https://whentofly.io/mcp?ch=github`
**Cursor** — add to `mcp.json`:
```json
{
"mcpServers": {
"whentofly": { "url": "https://whentofly.io/mcp?ch=github" }
}
}
```
**Any other MCP client** with remote (streamable HTTP) support: point it at
`https://whentofly.io/mcp`.
**ChatGPT** — use the [whentofly Custom GPT](https://whentofly.io) (MCP connectors are
Claude/Cursor-side for now).
## What the tools do
### `search_locations` — turn a place name into an exact identity
Returns typed values you pass straight through to `search_flights`:
- `city:SHA` — **every** airport in the Shanghai market
- `airport:SHA` — Hongqiao specifically, not Pudong
Plenty of IATA codes name both an airport and a whole city market — `SHA` is both — so
your agent should ask you which one you meant when more than one result looks plausible.
The catalog behind it covers 3,614 airports and 3,465 cities, so small regional airports
resolve too.
Already know the code? Pass it. This tool is for the long tail and for the
city-vs-airport cases.
### `search_flights` — cheapest round-trip in a flexible window
Give it a month or a date range plus min/max trip length ("5–9 days in October") and it
scans every valid depart/return pair, then sorts by price. Booking links on every fare,
airline names resolved.
Omit the destination — or say "anywhere" — and you get the cheapest places to fly from
your origin instead. "Where can I fly cheapest from Berlin in September?"
Each fare also gets a price level: *good*, *typical*, *high*, or *insufficient data* when
the route has no usable band. That says where today's price sits against the route's
usual range. It says nothing about which way fares are heading, and it will never tell
you to wait.
### Example prompts
- "Find the cheapest round trip Singapore → Tokyo in October, 5 to 9 days."
- "Where can I fly the cheapest from Berlin for a week in September?"
- "Is $450 a high price for NYC → Lisbon in November? Check flexible dates."
- "Plan me the cheapest 10–14 day trip to Japan in the next 3 months."
- "Flights from Zhangjiajie — resolve the airport first."
## What it doesn't do yet
Premium cabins aren't bookable. Ask for `cabin=business` or `first` and you may get
route-level price evidence in `metadata.route_price_check`, but no ranked fare with a
booking link. Our bookable fare source covers economy only. We could show you a business
price from somewhere else next to a link that goes elsewhere — we'd rather show you
nothing than a number the link won't honour.
Prices are cached indicators. Every response carries `metadata.freshness` so your agent
can see how stale a fare is; confirm the final price on the booking page.
## Pricing & funding
**Ranked for you, not for us.** Results are ordered by the cheapest real price we found,
whether or not that seller pays us — there's no fee a seller can pay to rank higher.
Free to use, no key. *Some* booking links are affiliate: if you book through one, the
partner may pay us a commission, never added to your fare. Each result reports its own
monetization, so an agent can tell which is which. Fares come from cached airline-ticket
data; always verify the final price on the booking page.
## For developers
The same search is available as a plain JSON API — `https://whentofly.io/search`
([docs](https://whentofly.io/docs)), plus `https://whentofly.io/locations?q=Shanghai` for
location resolution. This repo hosts documentation for the hosted MCP server; the service
itself is closed-source.
Questions / feedback: [hello@whentofly.io](mailto:hello@whentofly.io) or open an issue here.