Skip to content
Back to search

fli

Google Flights MCP, CLI and Python Library

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/punitarani/fli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/punitarani/fli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/punitarani--fli/badge.svg)](/listings/punitarani--fli)

HTML

<a href="/listings/punitarani--fli"><img src="/api/listings/punitarani--fli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install flights
# Install using pipx (recommended for CLI)
pipx install flights

# Get started with CLI
fli --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 689 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 🛫 Fli - Flight Search MCP Server and Library
  2. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/punitarani/fli)
  3. A powerful Python library that provides programmatic access to Google Flights data with an elegant CLI interface. Search
  4. flights, find the best deals, and filter results with ease.
  5. > 🚀 **What makes `fli` special?**
  6. > Unlike other flight search libraries that rely on web scraping, Fli directly interacts with Google Flights' API
  7. > through reverse engineering.
  8. > This means:
  9. >
  10. > * **Fast**: Direct API access means faster, more reliable results
  11. > * **Zero Scraping**: No HTML parsing, no browser automation, just pure API interaction
  12. > * **Reliable**: Less prone to breaking from UI changes
  13. > * **Modular**: Extensible architecture for easy customization and integration
  14. ## MCP Server
  15. ```bash
  16. pipx install flights
  17. # Run the MCP server on STDIO
  18. fli-mcp
  19. # Run the MCP server over HTTP (streamable)
  20. fli-mcp-http # serves at http://127.0.0.1:8000/mcp/
  21. ```
  22. ![MCP Demo](https://raw.githubusercontent.com/punitarani/fli/main/docs/assets/mcp-demo.gif)
  23. ### Connecting to Claude Desktop
  24. ```json
  25. {
  26. "mcpServers": {
  27. "fli": {
  28. "command": "/Users/<user>/.local/bin/fli-mcp"
  29. }
  30. }
  31. }
  32. ```
  33. > **Note**: Replace `<user>` with your actual username.
  34. > You can also find the path to the MCP server by running `which fli-mcp` in your terminal.
  35. ### MCP Tools Available
  36. The MCP server provides these main tools:
  37. | Tool | Description |
  38. |----------------------|-------------------------------------------------------------|
  39. | **`search_flights`** | Search for flights on a specific date with detailed filters |
  40. | **`search_dates`** | Find the cheapest travel dates across a flexible date range |
  41. | **`search_explore`** | Discover cheap destinations from an origin ("fly anywhere") |
  42. #### `search_flights` Parameters
  43. | Parameter | Type | Description |
  44. |---------------------|--------|-------------------------------------------------------------|
  45. | `origin` | string | Departure airport IATA code(s) — comma-separated for multi |
  46. | `destination` | string | Arrival airport IATA code(s) — comma-separated for multi |
  47. | `departure_date` | string | Travel date in YYYY-MM-DD format |
  48. | `return_date` | string | Return date for round trips (optional) |
  49. | `cabin_class` | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST |
  50. | `max_stops` | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS |
  51. | `departure_window` | string | Time window in 'HH-HH' format (e.g., '6-20') |
  52. | `airlines` | list | Filter by airline codes (e.g., ['BA', 'AA']) |
  53. | `exclude_airlines` | list | Airline IATA codes to **exclude** (e.g., ['DL', 'B6']) |
  54. | `alliance` | list | Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE |
  55. | `exclude_alliance` | list | Alliance names to **exclude** from results |
  56. | `min_layover` | int | Minimum layover duration in minutes (multi-stop only) |
  57. | `max_layover` | int | Maximum layover duration in minutes (multi-stop only) |
  58. | `top_n` | int | Round-trip only: outbound options expanded into return flights (default 5, 1-10) |
  59. | `currency` | string | ISO 4217 code (e.g. 'EUR', 'JPY') — flows to `curr=` param |
  60. | `language` | string | BCP-47 language code (e.g. 'en-GB') — flows to `hl=` param |
  61. | `country` | string | ISO 3166-1 alpha-2 country code (e.g. 'GB') for `gl=` param |
  62. | `sort_by` | string | CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME |
  63. | `passengers` | int | Number of adult passengers |
  64. | `children` | int | Number of children (ages 2-11) |
  65. | `infants_in_seat` | int | Number of infants (under 2) occupying their own seat |
  66. | `infants_on_lap` | int | Number of lap infants (under 2, no seat) |
  67. > Total travelers (`passengers + children + infants_in_seat + infants_on_lap`) must be
  68. > between 1 and 9, and `infants_on_lap` cannot exceed `passengers`.
  69. >
  70. > A round trip costs `1 + top_n` page fetches (one outbound search, plus one per
  71. > outbound candidate expanded into return flights), so `top_n` is capped at 10. Round-trip
  72. > results all from one airline? Raise `top_n`, or sort differently — the default sort only
  73. > ever expands the cheapest `top_n` outbounds, which are often the same carrier.
  74. #### `search_dates` Parameters
  75. | Parameter | Type | Description |
  76. |---------------------|--------|-------------------------------------------------------------|
  77. | `origin` | string | Departure airport IATA code(s) — comma-separated for multi |
  78. | `destination` | string | Arrival airport IATA code(s) — comma-separated for multi |
  79. | `start_date` | string | Start of date range in YYYY-MM-DD format |
  80. | `end_date` | string | End of date range in YYYY-MM-DD format |
  81. | `trip_duration` | int | Trip duration in days (for round-trips) |
  82. | `is_round_trip` | bool | Whether to search for round-trip flights |
  83. | `cabin_class` | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST |
  84. | `max_stops` | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS |
  85. | `departure_window` | string | Time window in 'HH-HH' format (e.g., '6-20') |
  86. | `airlines` | list | Filter by airline codes (e.g., ['BA', 'AA']) |
  87. | `exclude_airlines` | list | Airline IATA codes to **exclude** |
  88. | `alliance` | list | Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE |
  89. | `exclude_alliance` | list | Alliance names to **exclude** |
  90. | `min_layover` | int | Minimum layover duration in minutes |
  91. | `max_layover` | int | Maximum layover duration in minutes |
  92. | `currency` | string | ISO 4217 currency code (e.g. 'EUR', 'JPY') |
  93. | `language` | string | BCP-47 language code (e.g. 'en-GB') |
  94. | `country` | string | ISO 3166-1 alpha-2 country code (e.g. 'GB') |
  95. | `sort_by_price` | bool | Sort results by price (lowest first) |
  96. | `passengers` | int | Number of adult passengers |
  97. | `children` | int | Number of children (ages 2-11) |
  98. | `infants_in_seat` | int | Number of infants (under 2) occupying their own seat |
  99. | `infants_on_lap` | int | Number of lap infants (under 2, no seat) |
  100. > Same passenger limits as `search_flights`: total 1-9, `infants_on_lap` ≤ `passengers`.
  101. #### `search_explore` Parameters
  102. Powered by Google Flights Explore (`GetExploreDestinations`): one call returns
  103. dozens of destinations with their cheapest fares when the destination is
  104. flexible.
  105. | Parameter | Type | Description |
  106. |-----------------------|--------|--------------------------------------------------------------|
  107. | `origin` | string | Airport IATA code (e.g. 'JFK') or a city mid (e.g. '/m/04jpl') |
  108. | `destination` | string | ANYWHERE (default), EUROPE, SOUTHERN_EUROPE, ASIA, AFRICA, NORTH_AMERICA, SOUTH_AMERICA, OCEANIA, or a region or country knowledge-graph mid (not an airport or city) |
  109. | `departure_date` | string | Departure date in YYYY-MM-DD format (required) |
  110. | `round_trip` | bool | Price round trips instead of one-ways (needs a fixed trip length) |
  111. | `trip_min_nights` | int | Trip length in nights (round trips: one fixed value, 1-23) |
  112. | `trip_max_nights` | int | Must equal `trip_min_nights` for round trips |
  113. | `max_price` | int | Maximum fare cap |
  114. | `cabin_class` | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST |
  115. | `max_stops` | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS |
  116. | `airlines` | list | Filter by airline codes (e.g., ['BA', 'AA']) |
  117. | `exclude_airlines` | list | Airline IATA codes to **exclude** |
  118. | `alliance` | list | Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE |
  119. | `exclude_alliance` | list | Alliance names to **exclude** |
  120. | `max_flight_duration` | int | Maximum flight duration in minutes |
  121. | `passengers` | int | Number of adult passengers (default 1) |
  122. | `currency` | string | ISO 4217 currency code (e.g. 'EUR', 'JPY') |
  123. | `language` | string | BCP-47 language code (e.g. 'en-GB') |
  124. | `country` | string | ISO 3166-1 alpha-2 country code (e.g. 'GB') |
  125. | `sort_by_price` | bool | Sort destinations by price (default true) |
  126. | `limit` | int | Maximum number of destinations to return |
  127. Each priced destination includes the airline, stops, duration, destination
  128. airport, and a `flights_url` deep link; pass the `destination_airport` to
  129. `search_flights` for bookable itineraries.
  130. ## Quick Start
  131. ```bash
  132. pip install flights
  133. ```
  134. ```bash
  135. # Install using pipx (recommended for CLI)
  136. pipx install flights
  137. # Get started with CLI
  138. fli --help
  139. ```
  140. ![CLI Demo](https://raw.githubusercontent.com/punitarani/fli/main/docs/assets/cli-demo.png)
  141. ## Features
  142. * 🔍 **Powerful Search**
  143. * One-way flight searches
  144. * Multi-city flight searches
  145. * Flexible departure times
  146. * Multi-airline support
  147. * Cabin class selection
  148. * Stop preferences
  149. * Custom result sorting
  150. * 💺 **Cabin Classes**
  151. * Economy
  152. * Premium Economy
  153. * Business
  154. * First
  155. * 🎯 **Smart Sorting**
  156. * Price
  157. * Duration
  158. * Departure Time
  159. * Arrival Time
  160. * 🛡️ **Built-in Protection**
  161. * Rate limiting
  162. * Automatic retries
  163. * Comprehensive error handling
  164. * Input validation
  165. ## Search transport
  166. Searches are served by Google's public search page rather than the
  167. `FlightsFrontendService` RPC. Since 2026-08 `GetShoppingResults` and
  168. `GetCalendarGraph` require an `x-goog-batchexecute-bgr` header that only the
  169. page's own JavaScript can produce, so a plain HTTP client gets HTTP 200 with no
  170. payload. Fli issues `GET https://www.google.com/travel/flights?tfs=<protobuf>`
  171. instead and reads the results out of the page's inline `AF_initDataCallback`
  172. blob keyed `ds:1`.
  173. What that means in practice:
  174. * **Three filters are not supported.** `emissions`, `bags` and
  175. `exclude_basic_economy` have no `tfs` field and cannot be reconstructed from
  176. the decoded rows, so they are dropped with a warning. Stops, cabin,
  177. passengers, alliances and layover bounds ride in the request; airline
  178. include/exclude, price cap, max duration and departure windows are applied to
  179. the results after fetching.
  180. * **Multi-city raises `SearchUnsupportedError`.** Google loads those results
  181. client-side through the gated RPC, so the page carries no rows to read.
  182. Search each leg separately.
  183. * **`get_booking_options` is unavailable.** It calls `GetBookingResults`, which
  184. is gated the same way, and currently raises `SearchRejectedError`. The
  185. per-flight `tfs` booking deep links are built offline and still work.
  186. * **Fewer rows per search.** Expect roughly 20-45 itineraries, fewer than the
  187. old RPC returned — and a client-side filter cannot back-fill the list the way
  188. Google's server-side one did.
  189. * **Children and infants thin the results — sometimes to nothing.** Google
  190. prices those parties client-side, so the page inlines fewer itineraries for
  191. them, and in premium cabins often none (measured 2026-09: JFK→LHR economy
  192. 23 rows for one adult, 16 with an infant; SFO→NRT business 9 rows for one
  193. or two adults, 0 with a child). Extra adults cost nothing. An empty result
  194. for such a search does not mean the route has no flights — and neither
  195. does it mean this is why: `search()` only warns when the fetched page
  196. itself came back with zero rows, not when the caller's own airline/price/
  197. duration/window filter removed rows Google did return. An adults-only
  198. search shows the schedule.
  199. * **Date searches cost one page fetch per date.** The page has no calendar
  200. grid, so a range is priced date by date; one `SearchDates.search` covers at
  201. most 93 dates and a wider range raises `ValueError`. Budget for it: 93 dates
  202. across 10 workers is several hundred MB of pages and parsed JSON at peak.
  203. A sweep that never manages to load a single page — the shape a blocked or
  204. consent-gated client produces — gives up after a handful of dates rather than
  205. paying the retry budget on all of them. Only pages served without results
  206. count towards that: a timeout or a dropped connection says nothing about the
  207. dates not yet tried, so those never abandon a sweep. Measured with the real backoff: **42
  208. page fetches** (bounded at 45, so up to ~135 HTTP requests once the client's
  209. own retries multiply in) and about 4 seconds, the same whether the range is 30
  210. days or 93. Unbroken, a 93-date range would have cost 279 fetches and up to
  211. 837 requests. The bound is `(5 + worker count) x 3`, so raising
  212. `configure_concurrency` raises it proportionally. That breaker disarms for
  213. good the moment any page loads, even an empty one, so it cannot catch a
  214. sweep that is mostly timeouts around one lucky date — `SearchDates.search`
  215. raises that case too, whenever nothing priced and at least half the
  216. attempted dates never loaded. A minority of failures alongside real
  217. results, or alongside a confirmed-empty range (`None`), still returns
  218. normally but logs one warning naming the counts.
  219. * **A page occasionally arrives without results.** Roughly one request in sixty
  220. returns HTTP 200 with no `ds:1` blob; the client retries that case up to twice
  221. (0.5s then 1.5s) before raising `SearchParseError`. A healthy search never
  222. pays for it.
  223. * **`FLI_SOCS_COOKIE`.** EU/EEA IPs are redirected to Google's consent
  224. interstitial, which serves no `ds:1` blob. The client sends a pre-accepted
  225. `SOCS` consent cookie by default; set `FLI_SOCS_COOKIE` to change the value,
  226. or to an empty string to send none.
  227. * **`FLI_CA_BUNDLE` / `CURL_CA_BUNDLE` / `REQUESTS_CA_BUNDLE`.** Behind a
  228. TLS-intercepting corporate proxy, set one of these (checked in that order)
  229. to a PEM CA bundle path. A bad or missing path, or a certificate the bundle
  230. doesn't cover, raises `SearchCertificateError` naming the variable — the
  231. client does not retry it, since a fixed bundle either verifies or it doesn't.
  232. Read once per worker thread on its first request; changing the value
  233. doesn't affect a thread's already-created session.
  234. ## CLI Usage
  235. ### Search for Flights
  236. ```bash
  237. # Basic flight search
  238. fli flights JFK LHR 2026-10-25
  239. # Advanced search with filters
  240. fli flights JFK LHR 2026-10-25 \
  241. --time 6-20 \ # Departure time window (6 AM - 8 PM)
  242. --airlines BA,KL \ # Airlines (British Airways, KLM)
  243. --class BUSINESS \ # Cabin class
  244. --stops NON_STOP \ # Non-stop flights only
  245. --sort DURATION # Sort by duration
  246. # Alliance + exclude + locale (May-2026 filter additions)
  247. fli flights JFK LHR 2026-10-25 \
  248. --alliance ONEWORLD \
  249. --exclude-airlines AA \
  250. --min-layover 90 \
  251. --max-layover 360 \
  252. --currency EUR --language en-GB --country GB
  253. # Round trip: raise --top-n to see more airlines (default 5, max 10, costs 1 + top_n
  254. # page fetches per search)
  255. fli flights JFK LHR 2026-10-25 --return 2026-11-01 --top-n 8
  256. # Family mix: 2 adults, 1 child, 1 lap infant (total must be 1-9)
  257. fli flights JFK LHR 2026-10-25 --passengers 2 --children 1 --infants-on-lap 1
  258. ```
  259. > ⚠️ **Experimental**
  260. > `--format json` is experimental. The JSON schema may change while the machine-readable CLI contract settles.
  261. >
  262. > ```bash
  263. > # Return machine-readable flight results
  264. > fli flights JFK LHR 2026-10-25 --format json
  265. > ```
  266. ### Find Cheapest Dates
  267. ```bash
  268. # Basic date search
  269. fli dates JFK LHR
  270. # Advanced search with date range
  271. fli dates JFK LHR \
  272. --from 2026-01-01 \
  273. --to 2026-02-01 \
  274. --monday --friday # Only Mondays and Fridays
  275. ```
  276. > ⚠️ **Experimental**
  277. > `--format json` is experimental for date searches as well.
  278. >
  279. > ```bash
  280. > # Return machine-readable date search results
  281. > fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json
  282. > ```
  283. ### Multi-city Search
  284. ```bash
  285. # Two-leg multi-city trip
  286. fli multi --leg SEA,HKG,2026-12-26 --leg PEK,SEA,2027-01-02
  287. # Three-leg multi-city trip with filters
  288. fli multi \
  289. -l SEA,NRT,2026-12-26 \
  290. -l NRT,HKG,2026-12-30 \
  291. -l HKG,SEA,2027-01-05 \
  292. --class BUSINESS \
  293. --stops 0
  294. ```
  295. ### CLI Options
  296. #### Flights Command (`fli flights`)
  297. | Option | Description | Example |
  298. |-------------------------|--------------------------------------------|----------------------------------|
  299. | `--return, -r` | Return date | `2026-10-30` |
  300. | `--time, -t` | Departure time window | `6-20` |
  301. | `--airlines, -a` | Airline IATA codes | `BA,KL` |
  302. | `--exclude-airlines, -A` | Airline IATA codes to **exclude** | `DL,B6` |
  303. | `--alliance` | Restrict to alliance(s) | `ONEWORLD`, `SKYTEAM` |
  304. | `--exclude-alliance` | Alliance(s) to **exclude** | `STAR_ALLIANCE` |
  305. | `--min-layover` | Minimum layover (minutes) | `90` |
  306. | `--max-layover` | Maximum layover (minutes) | `360` |
  307. | `--top-n` | Round-trip only: outbound options expanded into return flights (default 5, 1-10) | `8` |
  308. | `--currency` | ISO 4217 currency code | `EUR`, `JPY` |
  309. | `--language` | BCP-47 language code (Google `hl=`) | `en-GB` |
  310. | `--country` | ISO 3166-1 alpha-2 country (`gl=`) | `GB` |
  311. | `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
  312. | `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |
  313. | `--sort, -o` | Sort results by | `CHEAPEST`, `DURATION` |
  314. | `--passengers, -p` | Number of adult passengers | `2` |
  315. | `--children` | Number of children (ages 2-11) | `1` |
  316. | `--infants-in-seat` | Number of infants occupying their own seat | `1` |
  317. | `--infants-on-lap` | Number of lap infants (must be ≤ adults) | `1` |
  318. | `--format` | Output format | `text`, `json` |
  319. > Total passengers (adults + children + infants) must be between 1 and 9.
  320. >
  321. > `--top-n` only applies to round trips (it is rejected if set on a one-way search) and
  322. > costs `1 + top_n` page fetches. Round-trip results all from one airline? Raise `--top-n`
  323. > (up to 10), or `--sort` differently — the default sort only expands the cheapest
  324. > `top_n` outbounds, which are often the same carrier.
  325. #### Dates Command (`fli dates`)
  326. | Option | Description | Example |
  327. |-------------------------|--------------------------------------------|--------------------------|
  328. | `--from` | Start date | `2026-01-01` |
  329. | `--to` | End date | `2026-02-01` |
  330. | `--duration, -d` | Trip duration in days | `3` |
  331. | `--round, -R` | Round-trip search | (flag) |
  332. | `--airlines, -a` | Airline IATA codes | `BA,KL` |
  333. | `--exclude-airlines, -A`| Airline IATA codes to **exclude** | `DL,B6` |
  334. | `--alliance` | Restrict to alliance(s) | `ONEWORLD` |
  335. | `--exclude-alliance` | Alliance(s) to **exclude** | `STAR_ALLIANCE` |
  336. | `--min-layover` | Minimum layover (minutes) | `90` |
  337. | `--max-layover` | Maximum layover (minutes) | `360` |
  338. | `--currency` | ISO 4217 currency code | `EUR`, `JPY` |
  339. | `--language` | BCP-47 language code | `en-GB` |
  340. | `--country` | ISO 3166-1 alpha-2 country | `GB` |
  341. | `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
  342. | `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |
  343. | `--time` | Departure time window | `6-20` |
  344. | `--sort` | Sort by price | (flag) |
  345. | `--[day]` | Day filters | `--monday`, `--friday` |
  346. | `--passengers, -p` | Number of adult passengers | `2` |
  347. | `--children` | Number of children (ages 2-11) | `1` |
  348. | `--infants-in-seat` | Number of infants occupying their own seat | `1` |
  349. | `--infants-on-lap` | Number of lap infants (must be ≤ adults) | `1` |
  350. | `--format` | Output format | `text`, `json` |
  351. #### Multi Command (`fli multi`)
  352. | Option | Description | Example |
  353. |------------------|--------------------------------------|--------------------------------|
  354. | `--leg, -l` | Flight leg (ORIGIN,DEST,DATE format) | `SEA,HKG,2026-12-26` |
  355. | `--time, -t` | Departure time window | `6-20` |
  356. | `--airlines, -a` | Airline IATA codes | `DL CX` |
  357. | `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
  358. | `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |
  359. | `--sort, -o` | Sort results by | `CHEAPEST`, `DURATION` |
  360. | `--passengers, -p` | Number of adult passengers | `2` |
  361. | `--children` | Number of children (ages 2-11) | `1` |
  362. | `--infants-in-seat` | Number of infants occupying their own seat | `1` |
  363. | `--infants-on-lap` | Number of lap infants (must be ≤ adults) | `1` |
  364. ## MCP Server Integration
  365. Fli includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to search for flights directly.
  366. This enables natural language flight search through conversation.
  367. ### Running the MCP Server
  368. ```bash
  369. # Run the MCP server on STDIO
  370. fli-mcp
  371. # Or with uv (for development)
  372. uv run fli-mcp
  373. # Or with make (for development)
  374. make mcp
  375. # Run the MCP server over HTTP (streamable)
  376. fli-mcp-http # serves at http://127.0.0.1:8000/mcp/
  377. ```
  378. ### Claude Desktop Configuration
  379. To use the flight search capabilities in Claude Desktop, add this configuration to your `claude_desktop_config.json`:
  380. **Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
  381. ```json
  382. {
  383. "mcpServers": {
  384. "flight-search": {
  385. "command": "fli-mcp",
  386. "args": []
  387. }
  388. }
  389. }
  390. ```
  391. After adding this configuration:
  392. 1. Restart Claude Desktop
  393. 2. You can now ask Claude to search for flights naturally:
  394. * "Find flights from JFK to LAX on December 25th"
  395. * "What are the cheapest dates to fly from NYC to London in January?"
  396. * "Search for business class flights from SFO to NRT with no stops"
  397. ## Python API Usage
  398. ### Basic Search Example
  399. ```python
  400. from datetime import datetime, timedelta
  401. from fli.models import (
  402. Airport,
  403. PassengerInfo,
  404. SeatType,
  405. MaxStops,
  406. SortBy,
  407. FlightSearchFilters,
  408. FlightSegment
  409. )
  410. from fli.search import SearchFlights
  411. # Create search filters
  412. filters = FlightSearchFilters(
  413. passenger_info=PassengerInfo(adults=1),
  414. flight_segments=[
  415. FlightSegment(
  416. departure_airport=[[Airport.JFK, 0]],
  417. arrival_airport=[[Airport.LAX, 0]],
  418. travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
  419. )
  420. ],
  421. seat_type=SeatType.ECONOMY,
  422. stops=MaxStops.NON_STOP,
  423. sort_by=SortBy.CHEAPEST,
  424. )
  425. # Search flights
  426. search = SearchFlights()
  427. flights = search.search(filters)
  428. # Process results
  429. for flight in flights:
  430. print(f"💰 Price: ${flight.price}")
  431. print(f"⏱️ Duration: {flight.duration} minutes")
  432. print(f"✈️ Stops: {flight.stops}")
  433. for leg in flight.legs:
  434. print(f"\n🛫 Flight: {leg.airline.value} {leg.flight_number}")
  435. print(f"📍 From: {leg.departure_airport.value} at {leg.departure_datetime}")
  436. print(f"📍 To: {leg.arrival_airport.value} at {leg.arrival_datetime}")
  437. ```
  438. ### Running Examples
  439. Runnable examples live in [`examples/python/`](examples/python):
  440. ```bash
  441. # Run examples with uv (recommended)
  442. uv run python examples/python/basic_one_way_search.py
  443. uv run python examples/python/round_trip_search.py
  444. uv run python examples/python/date_range_search.py
  445. # Or install dependencies first, then run directly
  446. pip install pydantic curl_cffi httpx
  447. python examples/python/basic_one_way_search.py
  448. ```
  449. **Available Examples:**
  450. * `basic_one_way_search.py` - Simple one-way flight search
  451. * `round_trip_search.py` - Round-trip flight booking
  452. * `date_range_search.py` - Find cheapest dates
  453. * `multi_city_search.py` - Multi-city itinerary across several legs
  454. * `advanced_filters_search.py` - Alliances, airline exclusions, layovers, locale
  455. * `complex_flight_search.py` - Advanced filtering and multi-passenger
  456. * `time_restrictions_search.py` - Time-based filtering
  457. * `date_search_with_preferences.py` - Weekend filtering
  458. * `price_tracking.py` - Price monitoring over time
  459. * `error_handling_with_retries.py` - Robust error handling
  460. * `result_processing.py` - Data analysis with pandas
  461. * `complex_round_trip_validation.py` - Advanced round-trip with validation
  462. * `advanced_date_search_validation.py` - Complex date search with filtering
  463. ## Examples
  464. Examples are organized by language, with parallel scripts so you can compare the
  465. two APIs:
  466. * **Python** — [`examples/python/`](examples/python)
  467. * **TypeScript** — [`examples/typescript/`](examples/typescript)
  468. ```bash
  469. # Python
  470. uv run python examples/python/complex_flight_search.py
  471. # TypeScript (from examples/typescript, after `bun install`)
  472. bun run multi_city_search.ts
  473. ```
  474. **Example Categories:**
  475. * **Basic Usage**: One-way, round-trip, date searches
  476. * **Advanced Filtering**: Time restrictions, airlines, alliances, seat classes, locale
  477. * **Data Analysis**: Price tracking, result processing with pandas
  478. * **Error Handling**: Retry logic, robust error management
  479. * **Complex Scenarios**: Multi-city, multi-passenger, validation, business rules
  480. Each example is self-contained — change the airports, dates, and filters at the top of the script to fit your search.
  481. ## TypeScript / JavaScript
  482. Fli is also available as a 1:1 TypeScript port, published to npm as
  483. [`fli-js`](https://www.npmjs.com/package/fli-js). Same models, same filter encoding,
  484. same direct-API approach.
  485. ```bash
  486. bun add fli-js # or: npm install fli-js
  487. ```
  488. ```ts
  489. import { Airport, FlightSearchFilters, FlightSegment, SearchFlights, SeatType } from "fli-js";
  490. const inDays = (n: number) => new Date(Date.now() + n * 86_400_000).toISOString().slice(0, 10);
  491. const filters = new FlightSearchFilters({
  492. passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
  493. flight_segments: [
  494. new FlightSegment({
  495. departure_airport: [[[Airport.JFK, 0]]],
  496. arrival_airport: [[[Airport.LAX, 0]]],
  497. travel_date: inDays(30),
  498. }),
  499. ],
  500. seat_type: SeatType.ECONOMY,
  501. });
  502. const results = await new SearchFlights().search(filters, { currency: "USD" });
  503. ```
  504. `fli-js` uses the same search-page transport as the Python package (see
  505. [Search transport](#search-transport) above), with the same consequences:
  506. `emissions` / `bags` / `exclude_basic_economy` are dropped with a warning,
  507. multi-city throws `SearchUnsupportedError`, `getBookingOptions` throws
  508. `SearchRejectedError`, date searches cost one page fetch per date and are
  509. capped at 93, and `FLI_SOCS_COOKIE` controls the consent cookie.
  510. The TypeScript source lives in [`fli-js/`](fli-js); see the
  511. [TypeScript Quick Start](https://punitarani.github.io/fli/typescript/quickstart/)
  512. for the full guide.
  513. ## Development
  514. ```bash
  515. # Clone the repository
  516. git clone https://github.com/punitarani/fli.git
  517. cd fli
  518. # Install dependencies with uv
  519. uv sync --all-extras
  520. # Run tests (offline only — no network access required)
  521. uv run pytest
  522. # Run linting
  523. uv run ruff check .
  524. uv run ruff format .
  525. # Build documentation
  526. uv run mkdocs serve
  527. # Or use the Makefile for common tasks
  528. make install-all # Install all dependencies
  529. make test # Run tests (offline only)
  530. make test-live # Run the small, stable live tests (real network)
  531. make lint # Check code style
  532. make format # Format code
  533. ```
  534. Tests that call the real Google Flights API are marked `live` and skipped by
  535. default (`--fuzz`, `--live` and `--all` are independent, skip-only gates —
  536. `--all` does *not* imply `--live`, and `--live` alone does *not* imply
  537. `--fuzz`). Run the small, stable live set with `make test-live` (or
  538. `pytest -m live --live`); the noisier 100-case fuzz-gated live test is a
  539. separate opt-in, `make test-live-fuzz` (`pytest --all -m live --live
  540. tests/search/test_search_flights_fuzz.py` — it needs `--all`/`--fuzz`
  541. *together with* `--live`, since it carries both markers).
  542. ### Docker Development
  543. ```bash
  544. # Build the devcontainer
  545. docker build -t fli-dev -f .devcontainer/Dockerfile .
  546. # Run CI inside the container
  547. docker run --rm fli-dev make lint test-all
  548. # Or run lint and tests separately
  549. docker run --rm fli-dev make lint
  550. docker run --rm fli-dev make test-all
  551. ```
  552. ### Running CI Locally with act
  553. To run GitHub Actions locally, install [act](https://github.com/nektos/act):
  554. ```bash
  555. brew install act
  556. # Run CI locally (lint + tests on Python 3.10-3.13)
  557. make ci
  558. # Or run CI inside Docker (no local act installation needed)
  559. make ci-docker
  560. ```
  561. ## Contributing
  562. Contributions are welcome! Please feel free to submit a Pull Request.
  563. ## License
  564. This project is licensed under the MIT License — see the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.