An enhanced, production-ready Model Context Protocol (MCP) Flight Search Server & CLI powered by SerpAPI Google Flights. Designed for AI Agents (Claude Desktop, Cursor, Antigravity, Windsurf) and human travelers.
Note: Forked from
arjunprabhulal/mcp-flight-searchwith comprehensive enhancements: smart multi-language city resolution, quota-saving local caching, full flight tier aggregation, exact layover durations, ground/rail alternative advisor, and a feature-rich CLI.
- 🌍 Smart City & Airport Resolver: Pass city names in English or Chinese (
Hanoi,河内,Guilin,桂林,Bangkok,曼谷,Tokyo,东京) or standard 3-letter IATA codes (HAN,KWL,BKK,TYO). Auto-resolves 300+ major worldwide hubs. - ⚡ Local Response Caching: Built-in 2-hour TTL cache (
~/.cache/mcp_flight_search/) prevents draining SerpAPI search credits on duplicate checks. Zero latency on cache hits. - 🛡️ Full Flight Coverage (
best+other): Ingests all flight tiers returned by Google Flights so regional and low-frequency airline schedules are never falsely reported as "no flights". - ⏱️ Exact Layover Parsing: Extracts precise layover durations (e.g.
Xiamen Gaoqi (13h 10m)) from SerpAPI layover metadata. - 🚄 Ground & High-Speed Rail Advisor: Automatically suggests ground/rail alternatives for corridors where high-speed trains or coaches are significantly faster and cheaper than flying (e.g., Hanoi ➔ Nanning / Guilin, Shenzhen ➔ Hong Kong, Shanghai ➔ Hangzhou, Tokyo ➔ Osaka).
- 💱 Multi-Currency Support: Full support for any ISO 4217 currency (
USD,CNY,EUR,VND, etc.) with robust regex price parsing. - 💻 Advanced CLI (
flight_search.py): Multi-day price trend scans (--days 7), round-trip searches (--return-date), and multi-format outputs (table,json,csv). - 🧪 Offline Test Suite: 11 unit tests ensuring zero regression across parsing, resolution, and caching.
# For Claude Desktop
npx -y @smithery/cli install @vecyang1/mcp-flight-search --client claude
# For Cursor
npx -y @smithery/cli install @vecyang1/mcp-flight-search --client cursor
# For Windsurf
npx -y @smithery/cli install @vecyang1/mcp-flight-search --client windsurf# Clone the repository
git clone https://github.com/vecyang1/mcp-flight-search.git
cd mcp-flight-search
# Using uv (recommended)
uv sync
# Or using pip
pip install -e .Set your SerpAPI key via environment variable or in a local .env file:
export SERP_API_KEY="your_serpapi_key_here"Search flights directly from your terminal:
# Search by Airport Code or City Name (English / Local)
python3 flight_search.py NRT BKK 2026-10-15 --currency USD
python3 flight_search.py Tokyo Bangkok 2026-10-15 --currency USD
# Multi-day price trend scan (finds daily lowest across N days)
python3 flight_search.py Tokyo Bangkok 2026-10-10 --days 7 --currency USD
# Round-trip flight search
python3 flight_search.py TYO SIN 2026-11-01 --return-date 2026-11-10 --currency USD
# Force live query (bypass local cache)
python3 flight_search.py HND BKK 2026-10-15 --no-cache
# Export to CSV or JSON
python3 flight_search.py NRT BKK 2026-10-15 --format csv --output-file tokyo_bangkok.csv🔍 Route: Tokyo (NRT) -> Bangkok (BKK) | 1 date(s)
Date Price (USD) Airline Dep/Arr Dur Stops
------------------------------------------------------------------------------------------------------------------
2026-10-15 $185 Zipair 2026-10-15 09:15 -> 2026-10-15 14:10 6h 55m Non-stop
2026-10-15 $215 AirAsia X 2026-10-15 11:30 -> 2026-10-15 16:35 7h 5m Non-stop
2026-10-15 $295 Thai Airways 2026-10-15 12:00 -> 2026-10-15 16:50 6h 50m Non-stop
------------------------------------------------------------------------------------------------------------------
✨ Cheapest: 2026-10-15 at $185 (Zipair, Non-stop)
💡 Ground/Rail Advisor: For regional city pairs (e.g., Tokyo ➔ Osaka, Shenzhen ➔ Hong Kong), high-speed rail options (Shinkansen bullet train / HSR) are automatically evaluated and recommended if faster and more cost-effective than flying.
To use this server with Claude Desktop, Cursor, Windsurf, or Antigravity, add it to your MCP configuration:
{
"mcpServers": {
"flight-search": {
"command": "python3",
"args": ["-m", "mcp_flight_search.server", "--connection_type", "stdio"],
"cwd": "/path/to/mcp-flight-search",
"env": {
"SERP_API_KEY": "your_serpapi_key_here"
}
}
}
}search_flights_tool:origin(string): Departure airport code or city name (e.g.NRT,Tokyo,HND,JFK)destination(string): Arrival airport code or city name (e.g.BKK,Bangkok,SIN,LHR)outbound_date(string): Departure date (YYYY-MM-DD)return_date(string, optional): Return date for round trips (YYYY-MM-DD)currency(string, default "USD"): ISO 4217 currency code (USD,EUR,GBP,JPY,CNY)no_cache(boolean, default false): Force live search bypassing local cache
ground_alternative_tool:origin(string): Origin airport or city namedestination(string): Destination airport or city name- Returns ground/high-speed rail alternative advice when available.
server_status: Check health of the MCP server.
import asyncio
from mcp_flight_search.services.search_service import search_flights
from mcp_flight_search.utils.ground_alternatives import get_ground_alternative
async def main():
# Pass city names or airport codes directly
flights = await search_flights("Tokyo", "Bangkok", "2026-10-15", currency="USD")
for f in flights[:3]:
print(f"{f['airline']} | ${f['price']} | {f['departure']} -> {f['arrival']} | Stops: {f['transit_cities']}")
tip = get_ground_alternative("TYO", "OSA")
if tip:
print(tip)
asyncio.run(main())Run the offline unit test suite:
uv run python3 -m unittest discover -s tests- Original base project created by Arjun Prabhulal.
- Enhanced & maintained by Vec Yang.
- Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.