[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72479":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},72479,"fli","punitarani\u002Ffli","punitarani","Google Flights MCP, CLI and Python Library","https:\u002F\u002Fdeepwiki.com\u002Fpunitarani\u002Ffli",null,"Python",2854,345,8,13,0,27,77,439,81,109.62,"MIT License",false,"main",true,[27,28,29,30,31,32],"api","flights-api","google-flights","google-flights-api","mcp","mcp-server","2026-06-12 04:01:06","# 🛫 Fli - Flight Search MCP Server and Library\n\n[![Ask DeepWiki](https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg)](https:\u002F\u002Fdeepwiki.com\u002Fpunitarani\u002Ffli)\n\nA powerful Python library that provides programmatic access to Google Flights data with an elegant CLI interface. Search\nflights, find the best deals, and filter results with ease.\n\n> 🚀 **What makes `fli` special?**\n> Unlike other flight search libraries that rely on web scraping, Fli directly interacts with Google Flights' API\n> through reverse engineering.\n> This means:\n>\n> * **Fast**: Direct API access means faster, more reliable results\n> * **Zero Scraping**: No HTML parsing, no browser automation, just pure API interaction\n> * **Reliable**: Less prone to breaking from UI changes\n> * **Modular**: Extensible architecture for easy customization and integration\n\n## MCP Server\n\n```bash\npipx install flights\n\n# Run the MCP server on STDIO\nfli-mcp\n\n# Run the MCP server over HTTP (streamable)\nfli-mcp-http  # serves at http:\u002F\u002F127.0.0.1:8000\u002Fmcp\u002F\n```\n\n![MCP Demo](https:\u002F\u002Fgithub.com\u002Fpunitarani\u002Ffli\u002Fblob\u002Fmain\u002Fdata\u002Fmcp-demo.gif)\n\n### Connecting to Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"fli\": {\n      \"command\": \"\u002FUsers\u002F\u003Cuser>\u002F.local\u002Fbin\u002Ffli-mcp\"\n    }\n  }\n}\n```\n\n> **Note**: Replace `\u003Cuser>` with your actual username.\n> You can also find the path to the MCP server by running `which fli-mcp` in your terminal.\n\n### MCP Tools Available\n\nThe MCP server provides two main tools:\n\n| Tool                 | Description                                                 |\n|----------------------|-------------------------------------------------------------|\n| **`search_flights`** | Search for flights on a specific date with detailed filters |\n| **`search_dates`**   | Find the cheapest travel dates across a flexible date range |\n\n#### `search_flights` Parameters\n\n| Parameter           | Type   | Description                                                 |\n|---------------------|--------|-------------------------------------------------------------|\n| `origin`            | string | Departure airport IATA code(s) — comma-separated for multi  |\n| `destination`       | string | Arrival airport IATA code(s) — comma-separated for multi    |\n| `departure_date`    | string | Travel date in YYYY-MM-DD format                            |\n| `return_date`       | string | Return date for round trips (optional)                      |\n| `cabin_class`       | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST                |\n| `max_stops`         | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS                  |\n| `departure_window`  | string | Time window in 'HH-HH' format (e.g., '6-20')                |\n| `airlines`          | list   | Filter by airline codes (e.g., ['BA', 'AA'])                |\n| `exclude_airlines`  | list   | Airline IATA codes to **exclude** (e.g., ['DL', 'B6'])      |\n| `alliance`          | list   | Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE     |\n| `exclude_alliance`  | list   | Alliance names to **exclude** from results                  |\n| `min_layover`       | int    | Minimum layover duration in minutes (multi-stop only)       |\n| `max_layover`       | int    | Maximum layover duration in minutes (multi-stop only)       |\n| `currency`          | string | ISO 4217 code (e.g. 'EUR', 'JPY') — flows to `curr=` param  |\n| `language`          | string | BCP-47 language code (e.g. 'en-GB') — flows to `hl=` param  |\n| `country`           | string | ISO 3166-1 alpha-2 country code (e.g. 'GB') for `gl=` param |\n| `sort_by`           | string | CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME         |\n| `passengers`        | int    | Number of adult passengers                                  |\n\n#### `search_dates` Parameters\n\n| Parameter           | Type   | Description                                                 |\n|---------------------|--------|-------------------------------------------------------------|\n| `origin`            | string | Departure airport IATA code(s) — comma-separated for multi  |\n| `destination`       | string | Arrival airport IATA code(s) — comma-separated for multi    |\n| `start_date`        | string | Start of date range in YYYY-MM-DD format                    |\n| `end_date`          | string | End of date range in YYYY-MM-DD format                      |\n| `trip_duration`     | int    | Trip duration in days (for round-trips)                     |\n| `is_round_trip`     | bool   | Whether to search for round-trip flights                    |\n| `cabin_class`       | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST                |\n| `max_stops`         | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS                  |\n| `departure_window`  | string | Time window in 'HH-HH' format (e.g., '6-20')                |\n| `airlines`          | list   | Filter by airline codes (e.g., ['BA', 'AA'])                |\n| `exclude_airlines`  | list   | Airline IATA codes to **exclude**                           |\n| `alliance`          | list   | Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE     |\n| `exclude_alliance`  | list   | Alliance names to **exclude**                               |\n| `min_layover`       | int    | Minimum layover duration in minutes                         |\n| `max_layover`       | int    | Maximum layover duration in minutes                         |\n| `currency`          | string | ISO 4217 currency code (e.g. 'EUR', 'JPY')                  |\n| `language`          | string | BCP-47 language code (e.g. 'en-GB')                         |\n| `country`           | string | ISO 3166-1 alpha-2 country code (e.g. 'GB')                 |\n| `sort_by_price`     | bool   | Sort results by price (lowest first)                        |\n| `passengers`        | int    | Number of adult passengers                                  |\n\n## Quick Start\n\n```bash\npip install flights\n```\n\n```bash\n# Install using pipx (recommended for CLI)\npipx install flights\n\n# Get started with CLI\nfli --help\n```\n\n![CLI Demo](https:\u002F\u002Fgithub.com\u002Fpunitarani\u002Ffli\u002Fblob\u002Fmain\u002Fdata\u002Fcli-demo.png)\n\n## Features\n\n* 🔍 **Powerful Search**\n    * One-way flight searches\n    * Multi-city flight searches\n    * Flexible departure times\n    * Multi-airline support\n    * Cabin class selection\n    * Stop preferences\n    * Custom result sorting\n\n* 💺 **Cabin Classes**\n    * Economy\n    * Premium Economy\n    * Business\n    * First\n\n* 🎯 **Smart Sorting**\n    * Price\n    * Duration\n    * Departure Time\n    * Arrival Time\n\n* 🛡️ **Built-in Protection**\n    * Rate limiting\n    * Automatic retries\n    * Comprehensive error handling\n    * Input validation\n\n## CLI Usage\n\n### Search for Flights\n\n```bash\n# Basic flight search\nfli flights JFK LHR 2026-10-25\n\n# Advanced search with filters\nfli flights JFK LHR 2026-10-25 \\\n    --time 6-20 \\             # Departure time window (6 AM - 8 PM)\n    --airlines BA,KL \\        # Airlines (British Airways, KLM)\n    --class BUSINESS \\        # Cabin class\n    --stops NON_STOP \\        # Non-stop flights only\n    --sort DURATION           # Sort by duration\n\n# Alliance + exclude + locale (May-2026 filter additions)\nfli flights JFK LHR 2026-10-25 \\\n    --alliance ONEWORLD \\\n    --exclude-airlines AA \\\n    --min-layover 90 \\\n    --max-layover 360 \\\n    --currency EUR --language en-GB --country GB\n```\n\n> ⚠️ **Experimental**\n> `--format json` is experimental. The JSON schema may change while the machine-readable CLI contract settles.\n>\n> ```bash\n> # Return machine-readable flight results\n> fli flights JFK LHR 2026-10-25 --format json\n> ```\n\n### Find Cheapest Dates\n\n```bash\n# Basic date search\nfli dates JFK LHR\n\n# Advanced search with date range\nfli dates JFK LHR \\\n    --from 2026-01-01 \\\n    --to 2026-02-01 \\\n    --monday --friday      # Only Mondays and Fridays\n```\n\n> ⚠️ **Experimental**\n> `--format json` is experimental for date searches as well.\n>\n> ```bash\n> # Return machine-readable date search results\n> fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json\n> ```\n\n### Multi-city Search\n\n```bash\n# Two-leg multi-city trip\nfli multi --leg SEA,HKG,2026-12-26 --leg PEK,SEA,2027-01-02\n\n# Three-leg multi-city trip with filters\nfli multi \\\n    -l SEA,NRT,2026-12-26 \\\n    -l NRT,HKG,2026-12-30 \\\n    -l HKG,SEA,2027-01-05 \\\n    --class BUSINESS \\\n    --stops 0\n```\n\n### CLI Options\n\n#### Flights Command (`fli flights`)\n\n| Option                  | Description                                | Example                          |\n|-------------------------|--------------------------------------------|----------------------------------|\n| `--return, -r`          | Return date                                | `2026-10-30`                     |\n| `--time, -t`            | Departure time window                      | `6-20`                           |\n| `--airlines, -a`        | Airline IATA codes                         | `BA,KL`                          |\n| `--exclude-airlines, -A` | Airline IATA codes to **exclude**         | `DL,B6`                          |\n| `--alliance`            | Restrict to alliance(s)                    | `ONEWORLD`, `SKYTEAM`            |\n| `--exclude-alliance`    | Alliance(s) to **exclude**                 | `STAR_ALLIANCE`                  |\n| `--min-layover`         | Minimum layover (minutes)                  | `90`                             |\n| `--max-layover`         | Maximum layover (minutes)                  | `360`                            |\n| `--currency`            | ISO 4217 currency code                     | `EUR`, `JPY`                     |\n| `--language`            | BCP-47 language code (Google `hl=`)        | `en-GB`                          |\n| `--country`             | ISO 3166-1 alpha-2 country (`gl=`)         | `GB`                             |\n| `--class, -c`           | Cabin class                                | `ECONOMY`, `BUSINESS`            |\n| `--stops, -s`           | Maximum stops                              | `NON_STOP`, `ONE_STOP`           |\n| `--sort, -o`            | Sort results by                            | `CHEAPEST`, `DURATION`           |\n| `--format`              | Output format                              | `text`, `json`                   |\n\n#### Dates Command (`fli dates`)\n\n| Option                  | Description                                | Example                  |\n|-------------------------|--------------------------------------------|--------------------------|\n| `--from`                | Start date                                 | `2026-01-01`             |\n| `--to`                  | End date                                   | `2026-02-01`             |\n| `--duration, -d`        | Trip duration in days                      | `3`                      |\n| `--round, -R`           | Round-trip search                          | (flag)                   |\n| `--airlines, -a`        | Airline IATA codes                         | `BA,KL`                  |\n| `--exclude-airlines, -A`| Airline IATA codes to **exclude**          | `DL,B6`                  |\n| `--alliance`            | Restrict to alliance(s)                    | `ONEWORLD`               |\n| `--exclude-alliance`    | Alliance(s) to **exclude**                 | `STAR_ALLIANCE`          |\n| `--min-layover`         | Minimum layover (minutes)                  | `90`                     |\n| `--max-layover`         | Maximum layover (minutes)                  | `360`                    |\n| `--currency`            | ISO 4217 currency code                     | `EUR`, `JPY`             |\n| `--language`            | BCP-47 language code                       | `en-GB`                  |\n| `--country`             | ISO 3166-1 alpha-2 country                 | `GB`                     |\n| `--class, -c`           | Cabin class                                | `ECONOMY`, `BUSINESS`    |\n| `--stops, -s`           | Maximum stops                              | `NON_STOP`, `ONE_STOP`   |\n| `--time`                | Departure time window                      | `6-20`                   |\n| `--sort`                | Sort by price                              | (flag)                   |\n| `--[day]`               | Day filters                                | `--monday`, `--friday`   |\n| `--format`              | Output format                              | `text`, `json`           |\n\n#### Multi Command (`fli multi`)\n\n| Option           | Description                          | Example                        |\n|------------------|--------------------------------------|--------------------------------|\n| `--leg, -l`      | Flight leg (ORIGIN,DEST,DATE format) | `SEA,HKG,2026-12-26`          |\n| `--time, -t`     | Departure time window                | `6-20`                         |\n| `--airlines, -a` | Airline IATA codes                   | `DL CX`                       |\n| `--class, -c`    | Cabin class                          | `ECONOMY`, `BUSINESS`          |\n| `--stops, -s`    | Maximum stops                        | `NON_STOP`, `ONE_STOP`         |\n| `--sort, -o`     | Sort results by                      | `CHEAPEST`, `DURATION`         |\n\n## MCP Server Integration\n\nFli includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to search for flights directly.\nThis enables natural language flight search through conversation.\n\n### Running the MCP Server\n\n```bash\n# Run the MCP server on STDIO\nfli-mcp\n\n# Or with uv (for development)\nuv run fli-mcp\n\n# Or with make (for development)\nmake mcp\n\n# Run the MCP server over HTTP (streamable)\nfli-mcp-http  # serves at http:\u002F\u002F127.0.0.1:8000\u002Fmcp\u002F\n```\n\n### Claude Desktop Configuration\n\nTo use the flight search capabilities in Claude Desktop, add this configuration to your `claude_desktop_config.json`:\n\n**Location**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json` (macOS)\n\n```json\n{\n  \"mcpServers\": {\n    \"flight-search\": {\n      \"command\": \"fli-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nAfter adding this configuration:\n\n1. Restart Claude Desktop\n2. You can now ask Claude to search for flights naturally:\n    * \"Find flights from JFK to LAX on December 25th\"\n    * \"What are the cheapest dates to fly from NYC to London in January?\"\n    * \"Search for business class flights from SFO to NRT with no stops\"\n\n## Python API Usage\n\n### Basic Search Example\n\n```python\nfrom datetime import datetime, timedelta\nfrom fli.models import (\n    Airport,\n    PassengerInfo,\n    SeatType,\n    MaxStops,\n    SortBy,\n    FlightSearchFilters,\n    FlightSegment\n)\nfrom fli.search import SearchFlights\n\n# Create search filters\nfilters = FlightSearchFilters(\n    passenger_info=PassengerInfo(adults=1),\n    flight_segments=[\n        FlightSegment(\n            departure_airport=[[Airport.JFK, 0]],\n            arrival_airport=[[Airport.LAX, 0]],\n            travel_date=(datetime.now() + timedelta(days=30)).strftime(\"%Y-%m-%d\"),\n        )\n    ],\n    seat_type=SeatType.ECONOMY,\n    stops=MaxStops.NON_STOP,\n    sort_by=SortBy.CHEAPEST,\n)\n\n# Search flights\nsearch = SearchFlights()\nflights = search.search(filters)\n\n# Process results\nfor flight in flights:\n    print(f\"💰 Price: ${flight.price}\")\n    print(f\"⏱️ Duration: {flight.duration} minutes\")\n    print(f\"✈️ Stops: {flight.stops}\")\n\n    for leg in flight.legs:\n        print(f\"\\n🛫 Flight: {leg.airline.value} {leg.flight_number}\")\n        print(f\"📍 From: {leg.departure_airport.value} at {leg.departure_datetime}\")\n        print(f\"📍 To: {leg.arrival_airport.value} at {leg.arrival_datetime}\")\n```\n\n### Running Examples\n\nWe provide 11 comprehensive examples in the `examples\u002F` directory that demonstrate various use cases:\n\n```bash\n# Run examples with uv (recommended)\nuv run python examples\u002Fbasic_one_way_search.py\nuv run python examples\u002Fround_trip_search.py\nuv run python examples\u002Fdate_range_search.py\n\n# Or install dependencies first, then run directly\npip install pydantic curl_cffi httpx\npython examples\u002Fbasic_one_way_search.py\n```\n\n**Available Examples:**\n\n* `basic_one_way_search.py` - Simple one-way flight search\n* `round_trip_search.py` - Round-trip flight booking\n* `date_range_search.py` - Find cheapest dates\n* `complex_flight_search.py` - Advanced filtering and multi-passenger\n* `time_restrictions_search.py` - Time-based filtering\n* `date_search_with_preferences.py` - Weekend filtering\n* `price_tracking.py` - Price monitoring over time\n* `error_handling_with_retries.py` - Robust error handling\n* `result_processing.py` - Data analysis with pandas\n* `complex_round_trip_validation.py` - Advanced round-trip with validation\n* `advanced_date_search_validation.py` - Complex date search with filtering\n\n> 💡 **Tip**: Examples include automatic dependency checking and will show helpful installation instructions if\n> dependencies are missing.\n\n## Examples\n\nFor comprehensive examples demonstrating all features, see the [`examples\u002F`](examples\u002F) directory:\n\n```bash\n# Quick test - run a simple example\nuv run python examples\u002Fbasic_one_way_search.py\n\n# Run all examples to explore different features\nuv run python examples\u002Fround_trip_search.py\nuv run python examples\u002Fcomplex_flight_search.py\nuv run python examples\u002Fprice_tracking.py\n```\n\n**Example Categories:**\n\n* **Basic Usage**: One-way, round-trip, date searches\n* **Advanced Filtering**: Time restrictions, airlines, seat classes\n* **Data Analysis**: Price tracking, result processing with pandas\n* **Error Handling**: Retry logic, robust error management\n* **Complex Scenarios**: Multi-passenger, validation, business rules\n\nEach example is self-contained and includes automatic dependency checking with helpful installation instructions.\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Fpunitarani\u002Ffli.git\ncd fli\n\n# Install dependencies with uv\nuv sync --all-extras\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check .\nuv run ruff format .\n\n# Build documentation\nuv run mkdocs serve\n\n# Or use the Makefile for common tasks\nmake install-all  # Install all dependencies\nmake test         # Run tests\nmake lint         # Check code style\nmake format       # Format code\n```\n\n### Docker Development\n\n```bash\n# Build the devcontainer\ndocker build -t fli-dev -f .devcontainer\u002FDockerfile .\n\n# Run CI inside the container\ndocker run --rm fli-dev make lint test-all\n\n# Or run lint and tests separately\ndocker run --rm fli-dev make lint\ndocker run --rm fli-dev make test-all\n```\n\n### Running CI Locally with act\n\nTo run GitHub Actions locally, install [act](https:\u002F\u002Fgithub.com\u002Fnektos\u002Fact):\n\n```bash\nbrew install act\n\n# Run CI locally (lint + tests on Python 3.10-3.13)\nmake ci\n\n# Or run CI inside Docker (no local act installation needed)\nmake ci-docker\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License — see the LICENSE file for details.\n","Fli 是一个强大的 Python 库，提供对 Google Flights 数据的编程访问，并附带优雅的命令行界面。项目通过反向工程直接与 Google Flights API 交互，而非依赖网页抓取，从而实现更快、更可靠的结果获取。其核心功能包括航班搜索、最佳价格查找及结果过滤等，支持零抓取、纯 API 交互模式，确保了系统的稳定性和可扩展性。此外，Fli 还提供了 MCP 服务器，能够以 HTTP 或 STDIO 方式运行，便于集成到其他应用中。该工具非常适合需要高效处理航班数据查询的应用场景，如旅行规划软件开发、数据分析等领域。",2,"2026-06-11 03:42:13","high_star"]