# whentofly [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/dimabalony/whentofly-mcp  
**GitHub Stars:** 3  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/whentofly

## Description
whentofly: flight search for AI agents — cheapest flexible-date round-trips + buy/wait verdict

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "whentofly": {
    "url": "https://whentofly.io)**"
  }
}
```

## Documentation & 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.