io.github.dimabalony/whentofly

whentofly — flight search for AI agents (MCP)

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

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:

{
  "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 (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), 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 or open an issue here.