# flights-mcp

An MCP server for searching flights using [Google Flights](https://www.google.com/travel/flights) data via [SerpAPI](https://serpapi.com/google-flights-api).

Built with [FastMCP](https://github.com/jlowin/fastmcp) for use with [Claude Code](https://claude.ai/code), Claude Desktop, or any MCP-compatible client.

## Why

Most flight MCP servers have incomplete airline coverage — missing low-cost carriers like Ryanair, easyJet, or Wizz Air. This server uses Google Flights (via SerpAPI) which aggregates all airlines, giving you the same results you'd see in the browser.

## Features

- Search one-way and round-trip flights with full Google Flights data
- Filter by stops, cabin class, price, and sort order
- Get booking links from airlines and travel agencies
- Price insights (price level, typical range, price history)
- All airlines included (Ryanair, easyJet, Iberia, Lufthansa, etc.)

## Tools

### `mcp_search_flights`

Search for flights on a specific route and date.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `departure` | str | required | Departure airport IATA code (e.g. `MAD`) |
| `arrival` | str | required | Arrival airport IATA code (e.g. `BER`) |
| `date` | str | required | Departure date `YYYY-MM-DD` |
| `return_date` | str | `None` | Return date for round trips |
| `passengers` | int | `1` | Number of adult passengers |
| `stops` | int | `None` | `1`=nonstop, `2`=1 stop max, `3`=2 stops max |
| `travel_class` | int | `1` | `1`=economy, `2`=premium, `3`=business, `4`=first |
| `sort_by` | int | `1` | `1`=top, `2`=price, `3`=departure, `4`=arrival, `5`=duration |
| `currency` | str | `EUR` | ISO currency code |
| `max_price` | int | `None` | Maximum price filter |

### `mcp_get_booking_options`

Get booking links for a specific flight using its `booking_token` from search results.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `booking_token` | str | required | Token from a flight search result |
| `currency` | str | `EUR` | ISO currency code |

## Setup

### 1. Get a SerpAPI key

Sign up at [serpapi.com](https://serpapi.com) and grab your API key. Free tier includes 100 searches/month.

### 2. Add to Claude Code

```bash
claude mcp add flights \
  -e SERPAPI_API_KEY=your_key_here \
  -- uv --directory /path/to/flights-mcp run flights-mcp
```

Or add manually to `~/.claude.json`:

```json
{
  "mcpServers": {
    "flights": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/flights-mcp", "run", "flights-mcp"],
      "env": {
        "SERPAPI_API_KEY": "your_key_here"
      }
    }
  }
}
```

### 3. Restart Claude Code

The server will be available after restart. Try: "Search for direct flights from Madrid to Berlin on March 19".

## Development

```bash
git clone https://github.com/chaosisnotrandomitisrhythmic/flights-mcp.git
cd flights-mcp
uv sync
SERPAPI_API_KEY=your_key uv run flights-mcp
```

## Architecture

```
src/flights_mcp/
├── __init__.py    # Exports mcp instance and run_server
├── server.py      # FastMCP server setup and tool definitions
└── tools.py       # Pure business logic (no MCP awareness)
```

- **`tools.py`** — Pure Python functions that call SerpAPI and return dicts. No MCP dependency. Easy to test independently.
- **`server.py`** — Thin `@mcp.tool()` wrappers that serialize results to JSON. Defines the MCP interface.

## License

MIT