Rihla MCP server

Rihla

Rihla (رحلة), "the journey." Named for Ibn Battuta's 14th-century travelogue —

the record of history's farthest-traveling explorer, who left Tangier for Mecca and

kept going for 29 years and 75,000 miles.

Flexible multi-leg, multi-airport flight search that finds the cheapest route across an entire itinerary — available as a CLI and as an MCP server for AI agents.

Consumer flight sites price one leg at a time. Rihla treats the whole trip as a single optimization problem:

*"Leave Montevideo — or Buenos Aires, it's a ferry ride away — around September 15

for Europe. Stay 20–30 days, then Japan for 15, then home. What's the cheapest

combination?"*

That query has three legs, flexible airports on both ends of each, a flexible departure window, and stay-duration constraints linking the legs. Rihla prices each leg's date×airport grid once, then finds the cheapest valid combinations in pure local compute — so even a 3–4 leg flexible query costs only a handful of API calls.

1. 1,297 USD   (44 days door-to-door)
     MVD -> AMS  2026-09-08  $    383  [mock, cached]  AA AA127
     FRA -> NRT  2026-10-07  $    481  [mock, cached]  KL KL411
     HND -> EZE  2026-10-22  $    433  [mock, cached]  AZ AZ933

2. 1,308 USD   (44 days door-to-door)
     MVD -> AMS  2026-09-14  $    446  [mock, cached]  AA AA127
     ...

Note the airport substitution at work: it enters Europe through Amsterdam, leaves from Frankfurt, and flies home into Buenos Aires — each leg independently picks the cheapest airport pair from its sets.

Quick start

Requires Python ≥ 3.10.

pip install rihla            # CLI
pip install "rihla[mcp]"     # CLI + MCP server

Runs offline out of the box (no keys needed — a deterministic mock data source):

RIHLA_PROFILE=mock rihla                # the canonical demo trip above
rihla examples/queries/canonical.json   # same trip, from a query file
rihla -i                                # build a query interactively

For live prices, copy .env.example to .env and add at least a Travelpayouts token (free). See Data sources.

Writing a query

A query is a small JSON file: your origin airports, the ordered stops, a departure window for the first leg, and how long to stay at each stop. Downstream date windows are derived — you never hand-compute "if I leave Sep 15 and stay 20–30 days, when do I fly to Tokyo?"

{
  "origins": ["MVD", "EZE", "AEP"],
  "stops": ["EUROPE", ["NRT", "HND"], "MVD_AREA"],
  "earliest": "2026-09-08",
  "latest": "2026-09-22",
  "stays": [[20, 30], [15, 15]],
  "date_step": 3,
  "top": 5
}

EUROPE (MAD, BCN, LIS, CDG, FCO, AMS, FRA), TOKYO (NRT, HND), MVD_AREA (MVD, EZE, AEP). Make the last stop your origin set to fly home.

• origins — IATA codes tried as one origin set; the cheapest wins per date.
• stops — each stop is a region name or a list of IATA codes. Built-in regions:

(len(stays) == len(stops) - 1).

• earliest / latest — the departure window for the first leg only.
• stays — [min, max] nights at each intermediate stop

• datestep** — sample every N days across date windows (coarser = fewer API calls).
• top — how many ranked combinations to return.
• currency — optional ISO 4217 code (default USD).

rihla -i walks you through these questions and prints the resulting JSON to save for reuse. Add --links to any run to show booking URLs.

Reading results

Rihla is honest about data quality rather than pretending everything is bookable:

Shortened. The full README is on GitHub.