Flight Search

A reliable Model Context Protocol (MCP) server for searching flights using the SerpAPI Google Flights engine. This server provides real-time flight search capabilities for both one-way and round-trip flights. Works well with claude ai desktop

- Real-time flight searchusing SerpAPI Google Flights
- One-way and round-tripflight support
- Multiple flight optionswith pricing, timing, and airline details
- JSON-RPC 2.0 compliantMCP protocol implementation
- Easy integrationwith Claude and other MCP clients
- Robust error handlingand logging

- Python 3.7 or higher
- SerpAPI account and API key (Get one here)
- MCP-compatible client (Claude, etc.)

mkdir -p ~/tools/flightsearch # Copy flight_search_server.py to ~/tools/flightsearch/

- Sign up atSerpAPI
- Get your API key from the dashboard

{ "flightsearch": { "command": "python3", "args": [ "/path/to/your/tools/flightsearch/flight_search_server.py", "--connection_type", "stdio" ], "env": { "SERP_API_KEY": "your_serpapi_key_here" } } }

For Claude Desktop, add this to yourclaude_desktop_config.json:

{ "mcpServers": { "flightsearch": { "command": "python3", "args": [ "/Users/yourusername/tools/flightsearch/flight_search_server.py", "--connection_type", "stdio" ], "env": { "SERP_API_KEY": "your_serpapi_key_here" } } } }

- origin(required): Origin airport code (e.g., "JFK", "LAX")
- destination(required): Destination airport code (e.g., "JFK", "LAX")
- outbound_date(required): Departure date in YYYY-MM-DD format
- return_date(optional): Return date for round-trip flights in YYYY-MM-DD format

# One-way flight search_flights(origin="JFK", destination="LAX", outbound_date="2025-07-01") # Round-trip flight search_flights(origin="JFK", destination="LAX", outbound_date="2025-07-01", return_date="2025-07-08")

Check if the flight search server is running.

{ "status": "success", "origin": "JFK", "destination": "LAX", "outbound_date": "2025-07-01", "return_date": null, "trip_type": "one_way", "flights": [ { "price": 199, "departure_time": "2025-07-01 08:40", "arrival_time": "2025-07-01 11:45", "airline": "Delta", "duration": 365, "stops": 0 }, { "price": 204, "departure_time": "2025-07-01 09:00", "arrival_time": "2025-07-01 12:00", "airline": "JetBlue", "duration": 360, "stops": 0 } ] }

# Set environment variable export SERP_API_KEY="your_api_key" # Run the server python3 flight_search_server.py --connection_type stdio

The server implements JSON-RPC 2.0 and supports these methods:

- initialize- Initialize the MCP connection
- tools/list- List available tools
- tools/call- Execute a tool
- ping- Health check
- notifications/initialized- Initialization notification

The server logs to stderr for debugging:

# View logs while running python3 flight_search_server.py --connection_type stdio 2>debug.log

1. "API request failed: 400 Client Error"

- Verify your SerpAPI key is valid
- Check that airport codes are correct (use IATA codes like "JFK", "LAX")
- Ensure date format is YYYY-MM-DD

2. "SERP_API_KEY environment variable not set"

- Make sure the API key is properly set in your MCP configuration
- Verify the environment variable name is exactlySERP_API_KEY

3. "JSON-RPC schema validation errors"

- Restart your MCP client to reload the server
- Check that you're using the latest version of the server

- Try different airport codes or dates
- Some routes may not be available for the selected date
- Check SerpAPI documentation for supported airports

# Add to the top of flight_search_server.py logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)

- SerpAPI Rate Limits: Check your SerpAPI plan for request limits
- Flight Data: Results depend on Google Flights data availability
- Date Range: Future dates only (cannot search past flights)
- Airport Codes: Must use valid IATA airport codes
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request

# Clone the repo git clone https://github.com/yourusername/flight-search-mcp.git cd flight-search-mcp # Install dependencies pip install requests # Run tests python3 test_mcp_protocol.py python3 test_flight_search.py

This project is licensed under the MIT License - see theLICENSEfile for details.

- SerpAPIfor providing the Google Flights API
- Anthropicfor the MCP protocol specification
- The open-source community for inspiration and feedback

- Issues: Open an issue on GitHub
- Questions: Check theSerpAPI documentation
- MCP Protocol: SeeAnthropic's MCP documentation

Perform web, news, and image searches using the Microsoft Bing Search API.