Google Flights MCP Server
---
title: Google Flights MCP
emoji: ✈️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---
# Google Flights MCP Server
<div align="center">
**A Model Context Protocol (MCP) server for intelligent flight search and travel planning**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](LICENSE)
</div>
---
## Overview
Integrates Google Flights data directly into your AI workflow with natural language searches, intelligent price comparisons, and automated travel planning.
**Data Sources:**
- **fast-flights (Primary):** Free, no API key required
- **SerpAPI (Fallback):** Richer data including flight numbers, layovers, carbon emissions, and multi-seller booking options — used when `SERPAPI_API_KEY` is set (250 free searches/month)
---
## Tools
| Tool | Description |
|------|-------------|
| `search_one_way_flights` | One-way flights for a specific date |
| `search_round_trip_flights` | Round-trip flights with fixed dates (supports `max_stops`) |
| `search_round_trips_in_date_range` | Search all round-trip combinations within a date range |
| `search_flights_by_airline` | Filter flights by airline codes or alliance (STAR_ALLIANCE, SKYTEAM, ONEWORLD) |
| `get_travel_dates` | Calculate travel dates relative to today |
| `generate_google_flights_url` | Generate a shareable Google Flights search link |
### Resources
- `airports://all` — Browse available airports
- `airports://{code}` — Get info for a specific airport (e.g. `airports://LAX`)
### Prompts
10 built-in travel planning prompts: `find_best_deal`, `weekend_getaway`, `last_minute_travel`, `business_trip`, `family_vacation`, `budget_backpacker`, `loyalty_program_optimizer`, `holiday_peak_travel`, `long_haul_international`, `stopover_explorer`.
---
## Quick Start
### Option 1: Install from PyPI
```bash
uvx mcp-server-google-flights
```
### Option 2: Run from source
```bash
git clone https://github.com/HaroldLeo/google-flights-mcp.git
cd google-flights-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
---
## Configuration
### Claude Desktop
```json
{
"mcpServers": {
"google-flights": {
"command": "uvx",
"args": ["mcp-server-google-flights"],
"env": {
"SERPAPI_API_KEY": "your_serpapi_key_here"
}
}
}
}
```
### From source
```json
{
"mcpServers": {
"google-flights": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/google-flights-mcp/src/mcp_server_google_flights/server.py"],
"env": {
"SERPAPI_API_KEY": "your_serpapi_key_here"
}
}
}
}
```
**Get a free SerpAPI key:** [serpapi.com/users/sign_up](https://serpapi.com/users/sign_up) (250 free searches/month)
---
## Remote Deployment (Hugging Face Spaces)
This server supports remote deployment as an SSE MCP server.
### Deploy to HF Spaces
1. Create a new Space at [huggingface.co/new-space](https://huggingface.co/new-space) with **Docker** SDK
2. Push this repository to the Space
3. (Optional) Add `SERPAPI_API_KEY` as a Space secret
The `Dockerfile` and transport switching are already configured — set `MCP_TRANSPORT=sse` (done automatically in the Dockerfile) to run in SSE mode.
### Connect to a deployed Space
```json
{
"mcpServers": {
"google-flights": {
"url": "https://YOUR-USERNAME-google-flights-mcp.hf.space/sse"
}
}
}
```
---
## Environment Variables
| Variable | Description |
|----------|-------------|
| `SERPAPI_API_KEY` | SerpAPI key for richer flight data (optional) |
| `MCP_TRANSPORT` | `stdio` (default) or `sse` for remote deployment |
| `HOST` | Host for SSE mode (default: `0.0.0.0`) |
| `PORT` | Port for SSE mode (default: `7860`) |
---
## Troubleshooting
**No flights found:** Try a different date or route. Google Flights rate-limits scraping — SerpAPI fallback is more reliable.
**401 error:** Update to the latest version. Older versions used a remote Playwright service that now requires auth.
**Slow searches:** `search_round_trips_in_date_range` is limited to 30 date combinations to avoid rate limiting. Narrow your date range or use `min_stay_days`/`max_stay_days`.
---
## License
MIT — see [LICENSE](LICENSE)
TDQS
Scored across 9 tools
The tools have overlapping purposes that could cause confusion, such as search_one_way_flights and search_direct_flights for one-way trips, and search_round_trip_flights and search_direct_flights for round-trips. However, descriptions provide some guidance to differentiate them, like the tip in search_round_trip_flights suggesting to use search_direct_flights for direct flights. This overlap reduces clarity but is partially mitigated by the documentation.
All tool names follow a consistent snake_case pattern with a verb_noun structure, such as generate_google_flights_url, get_multi_city_flights, and search_direct_flights. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.
With 9 tools, the count is reasonable for a flight search server, covering various search types and utilities. It is well-scoped but slightly heavy due to some overlapping tools, like multiple search functions that could potentially be consolidated, though each serves a distinct niche.
The tool set provides comprehensive coverage for flight search, including one-way, round-trip, multi-city, direct flights, airline filters, date range searches, and utilities like URL generation and date suggestions. There are no obvious gaps; it supports full lifecycle planning from search to results, with clear workflows and no dead ends.