flights

This MCP server provides a Python-based integration that exposes Google Flights data through the MCP interface. It offers tools to retrieve comprehensive flight information, identify the cheapest options, filter results by time constraints, and surface Google Flights' best-recommended flights. The server is designed to be run with uv (the Python-friendly MCP runner), and the Flights functionality is encapsulated in flights.py. You can use the available functions to build prompts for your agents or LLMs to obtain travel options efficiently.

To use it, start the uv-based server as configured in your MCP client ( Claude Desktop, Cursor, etc.). Once running, invoke the functions via your MCP client’s tool interface: get_general_flights_info(origin, destination, departure_date, [optional params]), get_cheapest_flights(...), get_best_flights(...), and get_time_filtered_flights(...). These tools return human-readable flight descriptions or structured data, tailored to your query (e.g., one-way trips, specific seats, passenger counts, and time-based constraints). Note that the current implementation focuses on one-way itineraries by default; round-trips are handled as two one-way segments if requested.

Examples of typical use include asking for the cheapest options between two airports on a given date, filtering results to flights after a certain time, or retrieving the top “best” flights as marked by Google Flights. Your agents can combine these tools to answer complex travel questions, such as finding the best business-class options within a time window or extracting general flight info for a route with multiple candidate flights.

Prerequisites:

• Python 3.8+ installed on your system
• uv installed in your Python environment (the MCP runner)
• Internet access for fetching data from Google Flights (as supported by the API wrapper behind flights.py)

Step-by-step installation:

1. Install uv (MCP runner) if you haven’t already. This often involves following the uv installation script or package for your OS. For macOS/Linux:

# Check if uv is installed
uv --version

# If not installed, install via your preferred method (example placeholder)
curl -fsSL https://raw.githubusercontent.com/your-uv-install/install.sh | sh

2. Clone or download this MCP server repository to your local machine and note the absolute path to the parent folder containing flights.py.

3. Ensure the mcp_config in your MCP client points to the correct uv executable and the correct directory where flights.py resides. For example, in your Claude Desktop or Cursor config, use:

{
  "mcpServers": {
    "flights": {
      "command": "/ABSOLUTE/PATH/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER",
        "run",
        "flights.py"
      ]
    }
  }
}

4. Start the MCP server via your client (the client will spawn uv with the provided command and arguments). Verify that the flights tool appears in your MCP Tools menu and is ready to accept queries.

5. (Optional) If you’re using a Windows environment, ensure uv is accessible in your PATH or provide the full Windows-style path to uv in the command field.

Tips and common issues:

• Ensure the absolute path to the repository (containing flights.py) is correctly set in the mcp config’s --directory argument.
• If you see “command not found” errors, verify that the uv executable has execute permissions and that the path is correct for your OS.
• The toolset currently focuses on one-way flights by default; if you need round-trip data, request two separate one-way queries or implement a wrapper that combines two legs.
• Time-based filters require correct formatting for target_time_str (HH:MM AM/PM) and state (before/after). Double-check time zone assumptions in your environment.
• If your MCP client caches tool definitions, restart the client after updating the mcp config to ensure the flights tool appears.
• For production deployments, consider pinning specific versions of uv and flights.py to avoid breaking changes during updates.