# 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
```bash
# Clone with submodules (recommended)
git clone --recursive https://github.com/shadyvb/mcp-skyscanner.git
cd mcp-skyscanner
```
**If you already cloned without submodules:**
```bash
git submodule update --init --recursive
```
### Step 2: Install Dependencies
```bash
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`):
```json
{
"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](https://github.com/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.
