Skyscanner MCP Server

An MCP (Model Context Protocol) server that exposes Skyscanner flight and airport search functionality to AI assistants like Claude Desktop and Cursor.

⚠️ Disclaimer

This project is experimental and intended for educational purposes only.

• This software is provided "as is" without any warranties
• Not intended for commercial use - Do not use this software in any commercial or production environment
• The Skyscanner API client library used here is reverse-engineered and may violate Skyscanner's Terms of Service
• Use at your own risk - The authors are not responsible for any consequences of using this software
• This project is for learning and experimentation with MCP servers and API integration

Features

• ✈️ Flight Search - Search for flights between airports with flexible date options
• 🛫 Airport Search - Find airports by name, city, or IATA code

Installation

Prerequisites

• Python 3.8 or higher
• Git (for submodule support)

Step 1: Clone the Repository

# Clone with submodules (recommended)
git clone --recursive https://github.com/shadyvb/mcp-skyscanner.git
cd mcp-skyscanner

If you already cloned without submodules:

git submodule update --init --recursive

Step 2: Install Dependencies

pip install -r requirements.txt

What gets installed:

• fastmcp - MCP server framework
• curl_cffi, typeguard, orjson - Skyscanner API dependencies
• skyscanner-api - Included as git submodule (automatically loaded by mcp_server.py)

The mcp_server.py automatically adds the vendor/skyscanner submodule to the Python path, so no additional installation steps are needed.

Usage

Setting Up Claude Desktop

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

   Open the config file and add the following (or merge with existing mcpServers):

{
  "mcpServers": {
    "skyscanner": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp-skyscanner/mcp_server.py"],
      "env": {
        "SKYSCANNER_LOCALE": "en-US",
        "SKYSCANNER_CURRENCY": "USD",
        "SKYSCANNER_MARKET": "US"
      }
    }
  }
}

Important notes:

• Replace /absolute/path/to/mcp-skyscanner/mcp_server.py with the absolute path to your mcp_server.py file
• Use python3 instead of python on macOS/Linux
• If using a virtual environment, use the full path to Python (e.g., /path/to/venv/bin/python3)

3. Restart Claude Desktop completely (quit and reopen the application)

4. Verify installation: After restarting, you should see the Skyscanner tools available in Claude Desktop. Try asking: "Search for flights from LHR to JFK on December 22nd"

Environment Variables

• SKYSCANNER_LOCALE: Locale code (default: "en-US")
• SKYSCANNER_CURRENCY: Currency code (default: "USD")
• SKYSCANNER_MARKET: Market region code (default: "US")

Available Tools

Once configured, the following tools are available in Claude Desktop:

search_airports

Search for airports by name, city, or IATA code.

Example usage in Claude:

• "Search for airports in London"
• "Find airports with code LHR"
• "What airports are in Cairo?"

Parameters:

• query (string, required): Airport name, city, or IATA code (e.g., "London", "LHR", "Cairo")
• depart_date (string, optional): Departure date in ISO format (e.g., "2025-12-22")
• return_date (string, optional): Return date in ISO format

Returns: List of airport objects with title, skyId (IATA code), and entity_id

search_flights

Search for flights between two airports.

Example usage in Claude:

• "Search for flights from London Heathrow to New York JFK on December 22nd"
• "Find flights from CAI to OPO on 2025-12-22"
• "Show me round-trip flights from LHR to JFK departing December 22, returning December 29"

Parameters:

• origin_airport_code (string, required): IATA code (e.g., "LHR", "CAI", "JFK")
• destination_airport_code (string, required): IATA code (e.g., "JFK", "OPO", "LHR")
• depart_date (string, required): Departure date in ISO format (e.g., "2025-12-22" or "2025-12-22T10:00:00")
• return_date (string, optional): Return date for round-trip flights
• cabin_class (string, optional): "economy", "premium_economy", "business", or "first" (default: "economy")
• adults (integer, optional): Number of adult passengers, 1-8 (default: 1)

Returns: Dictionary with session_id and buckets containing flight options:

• Best - Best overall options
• Cheapest - Lowest price options
• Fastest - Shortest duration options
• Direct - Non-stop flights (if available)

Example Usage

After setting up the MCP server in Claude Desktop, you can use natural language queries:

User: Search for flights from London Heathrow to New York JFK on December 22nd

Claude: I'll search for flights from London Heathrow (LHR) to New York JFK on December 22nd, 2025.

[Uses search_flights tool]

I found several flight options:
- Best: 8 options available
- Cheapest: 8 options available
- Fastest: 8 options available
- Direct: 3 non-stop options available

Would you like me to search for return flights as well?

Troubleshooting

Server Not Appearing

1. Check Python path: Use python3 instead of python on macOS, or use full path to Python executable
2. Verify dependencies: Run pip install -r requirements.txt to ensure all packages are installed
3. Initialize submodules: Run git submodule update --init --recursive if the vendor/skyscanner directory is empty
4. Check logs: Look for errors in ~/Library/Logs/Claude/mcp-server-skyscanner.log (macOS)
5. Test manually: Run python3 /path/to/mcp_server.py to check for import errors

Common Errors

• spawn python ENOENT: Use python3 instead of python in config
• ModuleNotFoundError: No module named 'fastmcp': Run pip install -r requirements.txt
• Date format errors: Ensure dates are in YYYY-MM-DD format and in the future

Error Responses

The server returns structured error responses:

• BannedWithCaptcha: Rate limited by Skyscanner
• Timeout: Search exceeded maximum retries
• InvalidDate: Date format or validation error
• AirportNotFound: Airport code not found

Notes

• Flight searches may take 10-30 seconds (API polls for results)
• Dates must be in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
• Dates must be in the future
• Airport codes are case-insensitive

License

GPL-3.0

Important: This license applies to the MCP server code only. The Skyscanner API client library (vendor/skyscanner) has its own license terms. Please review the license of the upstream repository before use.

Credits

• Skyscanner API client: irrisolto/skyscanner

Disclaimer (Reminder)

This project is experimental and for educational purposes only. It is not intended for commercial use. Use at your own risk.