Content
# 🛫 Fli - Flight Search MCP Server and Library
A powerful Python library that provides programmatic access to Google Flights data with an elegant CLI interface. Search
flights, find the best deals, and filter results with ease.
> 🚀 **What makes `fli` special?**
> Unlike other flight search libraries that rely on web scraping, Fli directly interacts with Google Flights' API
> through reverse engineering.
> This means:
>
> * **Fast**: Direct API access means faster, more reliable results
> * **Zero Scraping**: No HTML parsing, no browser automation, just pure API interaction
> * **Reliable**: Less prone to breaking from UI changes
> * **Modular**: Extensible architecture for easy customization and integration
## MCP Server
```bash
pipx install flights
# Run the MCP server on STDIO
fli-mcp
# Run the MCP server over HTTP (streamable)
fli-mcp-http # serves at http://127.0.0.1:8000/mcp/
```

### Connecting to Claude Desktop
```json
{
"mcpServers": {
"fli": {
"command": "/Users/<user>/.local/bin/fli-mcp"
}
}
}
```
> **Note**: Replace `<user>` with your actual username.
> You can also find the path to the MCP server by running `which fli-mcp` in your terminal.
### MCP Tools Available
The MCP server provides two main tools:
| Tool | Description |
|----------------------|-------------------------------------------------------------|
| **`search_flights`** | Search for flights on a specific date with detailed filters |
| **`search_dates`** | Find the cheapest travel dates across a flexible date range |
#### `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
```bash
pip install flights
```
```bash
# Install using pipx (recommended for CLI)
pipx install flights
# Get started with CLI
fli --help
```

## Features
* 🔍 **Powerful Search**
* One-way 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
```bash
# 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.
>
> ```bash
> # Return machine-readable flight results
> fli flights JFK LHR 2026-10-25 --format json
> ```
### Find Cheapest Dates
```bash
# 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.
>
> ```bash
> # Return machine-readable date search results
> fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json
> ```
### 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` |
## 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
```bash
# 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)
```json
{
"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
```python
from datetime import datetime, timedelta
from fli.models import (
Airport,
PassengerInfo,
SeatType,
MaxStops,
SortBy,
FlightSearchFilters,
FlightSegment
)
from fli.search import SearchFlights
# Create search filters
filters = FlightSearchFilters(
passenger_info=PassengerInfo(adults=1),
flight_segments=[
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
)
],
seat_type=SeatType.ECONOMY,
stops=MaxStops.NON_STOP,
sort_by=SortBy.CHEAPEST,
)
# Search flights
search = SearchFlights()
flights = search.search(filters)
# Process results
for flight in flights:
print(f"💰 Price: ${flight.price}")
print(f"⏱️ Duration: {flight.duration} minutes")
print(f"✈️ Stops: {flight.stops}")
for leg in flight.legs:
print(f"\n🛫 Flight: {leg.airline.value} {leg.flight_number}")
print(f"📍 From: {leg.departure_airport.value} at {leg.departure_datetime}")
print(f"📍 To: {leg.arrival_airport.value} at {leg.arrival_datetime}")
```
### Running Examples
We provide 11 comprehensive examples in the `examples/` directory that demonstrate various use cases:
```bash
# Run examples with uv (recommended)
uv run python examples/basic_one_way_search.py
uv run python examples/round_trip_search.py
uv run python examples/date_range_search.py
# Or install dependencies first, then run directly
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py
```
**Available Examples:**
* `basic_one_way_search.py` - Simple one-way flight search
* `round_trip_search.py` - Round-trip flight booking
* `date_range_search.py` - Find cheapest dates
* `complex_flight_search.py` - Advanced filtering and multi-passenger
* `time_restrictions_search.py` - Time-based filtering
* `date_search_with_preferences.py` - Weekend filtering
* `price_tracking.py` - Price monitoring over time
* `error_handling_with_retries.py` - Robust error handling
* `result_processing.py` - Data analysis with pandas
* `complex_round_trip_validation.py` - Advanced round-trip with validation
* `advanced_date_search_validation.py` - Complex date search with filtering
> 💡 **Tip**: Examples include automatic dependency checking and will show helpful installation instructions if
> dependencies are missing.
## Examples
For comprehensive examples demonstrating all features, see the [`examples/`](examples/) directory:
```bash
# Quick test - run a simple example
uv run python examples/basic_one_way_search.py
# Run all examples to explore different features
uv run python examples/round_trip_search.py
uv run python examples/complex_flight_search.py
uv run python examples/price_tracking.py
```
**Example Categories:**
* **Basic Usage**: One-way, round-trip, date searches
* **Advanced Filtering**: Time restrictions, airlines, seat classes
* **Data Analysis**: Price tracking, result processing with pandas
* **Error Handling**: Retry logic, robust error management
* **Complex Scenarios**: Multi-passenger, validation, business rules
Each example is self-contained and includes automatic dependency checking with helpful installation instructions.
## Development
```bash
# Clone the repository
git clone https://github.com/punitarani/fli.git
cd fli
# Install dependencies with uv
uv sync --all-extras
# Run tests
uv run pytest
# Run linting
uv run ruff check .
uv run ruff format .
# Build documentation
uv run mkdocs serve
# Or use the Makefile for common tasks
make install-all # Install all dependencies
make test # Run tests
make lint # Check code style
make format # Format code
```
### Docker Development
```bash
# Build the devcontainer
docker build -t fli-dev -f .devcontainer/Dockerfile .
# Run CI inside the container
docker run --rm fli-dev make lint test-all
# Or run lint and tests separately
docker run --rm fli-dev make lint
docker run --rm fli-dev make test-all
```
### Running CI Locally with act
To run GitHub Actions locally, install [act](https://github.com/nektos/act):
```bash
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
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License — see the LICENSE file for details.
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.