Fli Documentation

The Fli library examples cover a wide range of flight search scenarios. While most core features are available in both Python and TypeScript, some advanced features are currently specific to the Python implementation.

Available in both Python and TypeScript:

• One-way search
• Round-trip search
• Cheapest dates in a range
• Multi-city itinerary
• Advanced filters (alliances, exclusions, layovers, locale)
• Error handling & client tuning

Available in Python only:

• Time-restricted search
• Day-of-week / weekend date preferences
• Validation-heavy round trips & date ranges
• Price tracking over time
• Result processing (using pandas)

If you are working within the repository and have uv installed, you can run the examples directly from the repo root to ensure all dependencies are handled.

uv run python examples/python/basic_one_way_search.py

Install the fli-js library using your preferred package manager.

npm i fli-js   # or: pnpm add fli-js / yarn add fli-js / bun add fli-js

Fli is available as a TypeScript port published to npm as fli-js. It provides the same models, filter encoding, and direct-API approach as the Python version.

bun add fli-js   # or: npm install fli-js

For web-based integrations, you can run the server over a streamable HTTP transport. By default, it binds to 127.0.0.1:8000 and serves the MCP endpoint at /mcp/ (e.g., http://127.0.0.1:8000/mcp/).

Use the fli-mcp-http command, or override the host and port by calling run_http directly in Python.

After installation, verify that the commands are available in your terminal. If the commands are not found, run python3 -m pipx ensurepath and restart your terminal session.

fli --help
fli-mcp --help
which fli-mcp

Once the Fli MCP server is connected to an MCP client like Claude Desktop, you can perform flight searches using natural language. The server provides the following tools to the LLM:

• search_flights: Used for specific flight searches (e.g., finding flights between specific airports or with specific cabin classes).
• search_dates: Used to find the cheapest or most suitable dates for travel between two locations.
• get_booking_options: Used to retrieve available booking details.

To run the provided Python examples, you can use uv (recommended) or install the required dependencies manually.

Required dependencies for manual installation:

• pydantic
• curl_cffi
• httpx

# Run with uv (recommended)
uv run python examples/python/basic_one_way_search.py
uv run python examples/python/date_range_search.py

# Or install dependencies and run directly
pip install pydantic curl_cffi httpx
python examples/python/basic_one_way_search.py

You can run the examples using Bun (recommended for direct .ts execution) or via Node.js using a TypeScript loader like tsx.

Using Bun

Run specific files or use the predefined package scripts for common search patterns.

Using Node.js

Use npx tsx to execute the TypeScript files directly.

# Using Bun
bun run basic_one_way_search.ts
# or via package scripts:
bun run basic         # one-way
bun run round-trip    # round trip
bun run dates         # cheapest dates in a range
bun run multi-city    # 3-leg itinerary
bun run advanced      # alliances + exclusions + locale
bun run errors        # client tuning + typed error handling

# Using Node
npx tsx basic_one_way_search.ts

To run GitHub Actions locally, install act and use the provided Makefile commands.

brew install act

# Run CI locally (lint + tests on Python 3.10-3.13)
make ci

# Or run CI inside Docker (no local act installation needed)
make ci-docker