search_flights Parameters

| Parameter | Type | Description | |--------------------|--------|-----------------------------------------------------| | origin | string | Departure airport IATA code (e.g., 'JFK') | | destination | string | Arrival airport IATA code (e.g., 'LHR') | | departure_date | string | Travel date in YYYY-MM-DD format | | return_date | string | Return date for round trips (optional) | | cabin_class | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST | | max_stops | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS | | departure_window | string | Time window in 'HH-HH' format (e.g., '6-20') | | airlines | list | Filter by airline codes (e.g., ['BA', 'AA']) | | sort_by | string | CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME | | passengers | int | Number of adult passengers |

search_dates Parameters

| Parameter | Type | Description | |--------------------|--------|----------------------------------------------| | origin | string | Departure airport IATA code (e.g., 'JFK') | | destination | string | Arrival airport IATA code (e.g., 'LHR') | | start_date | string | Start of date range in YYYY-MM-DD format | | end_date | string | End of date range in YYYY-MM-DD format | | trip_duration | int | Trip duration in days (for round-trips) | | is_round_trip | bool | Whether to search for round-trip flights | | cabin_class | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST | | max_stops | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS | | departure_window | string | Time window in 'HH-HH' format (e.g., '6-20') | | airlines | list | Filter by airline codes (e.g., ['BA', 'AA']) | | sort_by_price | bool | Sort results by price (lowest first) | | passengers | int | Number of adult passengers |

Quick Start

pip install flights

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

# Get started with CLI
fli --help

Features

• 🔍 Powerful Search

  • One-way flight searches
  • Multi-city flight searches
  • Flexible departure times
  • Multi-airline support
  • Cabin class selection
  • Stop preferences
  • Custom result sorting

• 💺 Cabin Classes

  • Economy
  • Premium Economy
  • Business
  • First

• 🎯 Smart Sorting

  • Price
  • Duration
  • Departure Time
  • Arrival Time

• 🛡️ Built-in Protection

  • Rate limiting
  • Automatic retries
  • Comprehensive error handling
  • Input validation

CLI Usage

Search for Flights

# Basic flight search
fli flights JFK LHR 2026-10-25

# Advanced search with filters
fli flights JFK LHR 2026-10-25 \
    --time 6-20 \             # Departure time window (6 AM - 8 PM)
    --airlines BA,KL \        # Airlines (British Airways, KLM)
    --class BUSINESS \        # Cabin class
    --stops NON_STOP \        # Non-stop flights only
    --sort DURATION           # Sort by duration

⚠️ Experimental --format json is experimental. The JSON schema may change while the machine-readable CLI contract settles.

# Return machine-readable flight results
fli flights JFK LHR 2026-10-25 --format json

Find Cheapest Dates

# Basic date search
fli dates JFK LHR

# Advanced search with date range
fli dates JFK LHR \
    --from 2026-01-01 \
    --to 2026-02-01 \
    --monday --friday      # Only Mondays and Fridays

⚠️ Experimental --format json is experimental for date searches as well.

# Return machine-readable date search results
fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json

Multi-city Search

# Two-leg multi-city trip
fli multi --leg SEA,HKG,2026-12-26 --leg PEK,SEA,2027-01-02

# Three-leg multi-city trip with filters
fli multi \
    -l SEA,NRT,2026-12-26 \
    -l NRT,HKG,2026-12-30 \
    -l HKG,SEA,2027-01-05 \
    --class BUSINESS \
    --stops 0

CLI Options

Flights Command (fli flights)

| Option | Description | Example | |------------------|-----------------------|------------------------| | --return, -r | Return date | 2026-10-30 | | --time, -t | Departure time window | 6-20 | | --airlines, -a | Airline IATA codes | BA,KL | | --class, -c | Cabin class | ECONOMY, BUSINESS | | --stops, -s | Maximum stops | NON_STOP, ONE_STOP | | --sort, -o | Sort results by | CHEAPEST, DURATION | | --format | Output format | text, json |

Dates Command (fli dates)

| Option | Description | Example | |--------------------|------------------------|------------------------| | --from | Start date | 2026-01-01 | | --to | End date | 2026-02-01 | | --duration, -d | Trip duration in days | 3 | | --round, -R | Round-trip search | (flag) | | --airlines, -a | Airline IATA codes | BA,KL | | --class, -c | Cabin class | ECONOMY, BUSINESS | | --stops, -s | Maximum stops | NON_STOP, ONE_STOP | | --time | Departure time window | 6-20 | | --sort | Sort by price | (flag) | | --[day] | Day filters | --monday, --friday | | --format | Output format | text, json |

Multi Command (fli multi)

| Option | Description | Example | |------------------|--------------------------------------|--------------------------------| | --leg, -l | Flight leg (ORIGIN,DEST,DATE format) | SEA,HKG,2026-12-26 | | --time, -t | Departure time window | 6-20 | | --airlines, -a | Airline IATA codes | DL CX | | --class, -c | Cabin class | ECONOMY, BUSINESS | | --stops, -s | Maximum stops | NON_STOP, ONE_STOP | | --sort, -o | Sort results by | CHEAPEST, DURATION |

MCP Server Integration

Fli includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to search for flights directly. This enables natural language flight search through conversation.

Running the MCP Server

# Run the MCP server on STDIO
fli-mcp

# Or with uv (for development)
uv run fli-mcp

# Or with make (for development)
make mcp

# Run the MCP server over HTTP (streamable)
fli-mcp-http  # serves at http://127.0.0.1:8000/mcp/

Claude Desktop Configuration

To use the flight search capabilities in Claude Desktop, add this configuration to your claude_desktop_config.json:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "flight-search": {
      "command": "fli-mcp",
      "args": []
    }
  }
}

After adding this configuration:

1. Restart Claude Desktop
2. You can now ask Claude to search for flights naturally:
   • "Find flights from JFK to LAX on December 25th"
   • "What are the cheapest dates to fly from NYC to London in January?"
   • "Search for business class flights from SFO to NRT with no stops"

Python API Usage

Basic Search Example

from datetime import datetime, timedelta
from fli.models import (
    Airport,
    PassengerInfo,
    SeatType,
    MaxStops,
    SortBy,
    FlightSearchFilters,
    FlightSegment
)
from fli.search import SearchFligh