# FlightClaw agents

Search, price-track and book flights from your AI assistant. FlightClaw covers
about 300 airlines, remembers your travellers and preferences, and emails you
when a tracked fare drops.

## Option 1: Hosted MCP (recommended)

Server URL: `https://mcp.flightclaw.com/mcp` (streamable HTTP, OAuth sign-in).
Nothing to install.

| Client | Setup |
|---|---|
| Claude (web / desktop) | Settings > Connectors > Add custom connector > paste `https://mcp.flightclaw.com/mcp` |
| ChatGPT | Settings > Apps & Connectors > Create (developer mode) > paste `https://mcp.flightclaw.com/mcp` |
| Claude Code | `claude mcp add --transport http flightclaw https://mcp.flightclaw.com/mcp` |
| Cursor | [One-click install](https://cursor.com/en/install-mcp?name=flightclaw&config=eyJ1cmwiOiJodHRwczovL21jcC5mbGlnaHRjbGF3LmNvbS9tY3AifQ%3D%3D), or add `{"mcpServers":{"flightclaw":{"url":"https://mcp.flightclaw.com/mcp"}}}` to `~/.cursor/mcp.json` |
| VS Code | [One-click install](https://vscode.dev/redirect/mcp/install?name=flightclaw&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.flightclaw.com%2Fmcp%22%7D), or `code --add-mcp '{"name":"flightclaw","type":"http","url":"https://mcp.flightclaw.com/mcp"}'` |
| Windsurf | Add `{"mcpServers":{"flightclaw":{"serverUrl":"https://mcp.flightclaw.com/mcp"}}}` to `~/.codeium/windsurf/mcp_config.json` |

### Hosted tools

| Group | Tools |
|---|---|
| Search | `search_flights`, `search_multi_city`, `recommend_flights`, `get_offer`, `get_seat_map` |
| Booking | `create_checkout`, `pay_checkout`, `get_checkout_status`, `list_orders`, `get_order`, `request_change`, `cancel_order` |
| Price tracking | `track_flight`, `list_tracked`, `remove_tracked` (checked daily, email alert on a drop) |
| Profile | `get_me`, `set_me`, `save_traveler`, `list_travelers`, `get_traveler`, `delete_traveler`, `save_group`, `list_groups`, `get_group`, `delete_group`, `get_preferences`, `set_preferences`, `save_card`, `list_cards`, `delete_card`, `set_points_balance`, `list_points` |
| Trips | `log_trip`, `list_trips`, `get_trip`, `trips_followup`, `record_trip_feedback` |

### Booking and payment

1. `search_flights` returns offers. Each `total_amount` includes the FlightClaw booking fee.
2. `create_checkout` returns a `checkout_url` and the exact `total_amount` + `total_currency`. Nothing is charged yet.
3. Pay one of two ways:
   - **Checkout link**: the traveller opens `checkout_url` and pays by card.
   - **Headless with Stripe Link**: the agent creates a Link spend request for exactly
     `total_amount` (fare + booking fee), the user approves it in Link, and the agent pays
     on `checkout_url` with the Link shared payment token / virtual card. The agent never
     pays more than the approved amount.
4. `get_checkout_status` until `completed`, then `get_order` for the booking reference.

The agent never asks for card numbers.

## Option 2: Local open-source server

The rest of this README covers the self-hosted Python server in this repo.
It searches Google Flights and tracks prices locally with no account.

## Local MCP server

FlightClaw runs as a local [MCP](https://modelcontextprotocol.io) server, giving any MCP-compatible client (Claude Code, Claude Desktop, etc.) access to flight search and tracking tools.

### Setup

```bash
# Install dependencies
pip install "flights==0.9.0" "mcp[cli]<2" fastmcp pydantic-settings

# Add to Claude Code
claude mcp add flightclaw -- python3 /path/to/agents/server.py
```

Or in Claude Desktop, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "flightclaw": {
      "command": "python3",
      "args": ["/path/to/agents/server.py"]
    }
  }
}
```

### Tools

| Tool | Description |
|------|-------------|
| `search_flights` | Search Google Flights for prices on a route |
| `search_dates` | Find cheapest dates to fly across a date range (calendar view) |
| `track_flight` | Add a route to price tracking with optional target price |
| `check_prices` | Check all tracked flights for price changes and alerts |
| `list_tracked` | List all tracked flights with price history |
| `remove_tracked` | Remove a route from tracking |

### Search filters

All search tools support:

- **Passengers** - adults, children, infants (in seat or on lap)
- **Airlines** - filter to specific carriers (e.g. `BA,AA,DL`)
- **Price limit** - max price in USD
- **Duration** - max total flight time in minutes
- **Times** - earliest/latest departure and arrival hours
- **Layovers** - max layover duration in minutes
- **Sorting** - by BEST, CHEAPEST, DEPARTURE, ARRIVAL, or DURATION
- **Multi-airport** - comma-separated codes (e.g. `LHR,MAN`)
- **Date ranges** - `date_to` for searching each day in a range

### Example prompts

- "Search flights from LHR to JFK on 2025-08-01 in business class"
- "Find nonstop BA or VS flights LHR to JFK departing after 8am"
- "What are the cheapest dates to fly LHR to JFK in July?"
- "Search for 2 adults and 1 child, LHR to JFK, under $500"
- "Track LHR to SFO on 2025-07-01 with a target price of $400"
- "Check my tracked flights for price drops"

## CLI Scripts

The original CLI scripts are still available in `scripts/`:

```bash
# Search flights
python scripts/search-flights.py LHR JFK 2025-07-01 --cabin BUSINESS

# Multiple airports and date ranges
python scripts/search-flights.py LHR,MAN JFK,EWR 2025-07-01 --date-to 2025-07-05

# Track a route
python scripts/track-flight.py LHR JFK 2025-07-01 --target-price 400

# Check for price drops (good for cron)
python scripts/check-prices.py --threshold 5

# List tracked flights
python scripts/list-tracked.py
```

## How it works

- Queries Google Flights via the `fli` library
- Prices returned in user's local currency (auto-detected from IP)
- Price history persists in `data/tracked.json`
- Supports one-way and round trips, all cabin classes (economy to first)
- Filter by airline, price, duration, departure/arrival times, layover duration
- Multi-airport and date-range searches expand into all combinations
- Date search finds the cheapest day to fly across a range

## Install (OpenClaw)

```bash
npx skills add flightclaw/agents
```

## Install (Grok)

```
/plugin marketplace add xai-org/plugin-marketplace
/plugin install flightclaw
```

## Install (Claude Code)

```
/plugin marketplace add flightclaw/agents
/plugin install flightclaw@flightclaw
```

## Install (Cursor)

```
/plugin marketplace add flightclaw/agents
/plugin install flightclaw
```

## Install (Gemini CLI)

```bash
gemini extensions install https://github.com/flightclaw/agents
```

Each client reads its own manifest from this repo — `.grok-plugin/`,
`.claude-plugin/`, `.cursor-plugin/` and `gemini-extension.json` — and they all
connect to the hosted server at `https://mcp.flightclaw.com/mcp`. To run the
local server instead, use the setup in "Local MCP server" above.

## The local server

The local server runs `server.py` through `uv`, which resolves the pinned
dependencies at start-up. Install [uv](https://docs.astral.sh/uv/) first; no
other setup step runs on your machine.

### What the local server reaches, and what it needs

| Endpoint | Purpose | Credentials |
|---|---|---|
| `google.com/travel/flights` (via the `fli` library) | Flight search and price tracking | none |
| `FLIGHTCLAW_API_URL` (the private flightclaw-api Worker) | Traveller profiles, preferences, cards, groups, trip history, Duffel booking and Link virtual-card payment | `FLIGHTCLAW_API_KEY` |
| Kiwi Tequila (`api.tequila.kiwi.com`) | Optional bookability check; hand-off deep links to `kiwi.com` and `skyscanner.net` | `KIWI_API_KEY`, `KIWI_AFFILID` |

Search and price tracking work with no credentials at all. Every other group of
tools stays inactive until its variables are set:

| Variable | Effect when unset |
|---|---|
| `FLIGHTCLAW_API_URL`, `FLIGHTCLAW_API_KEY` | Profile, booking and payment tools return "not configured" |
| `FLIGHTCLAW_TENANT` | Server default tenant is used |
| `KIWI_API_KEY`, `KIWI_AFFILID` | Kiwi coverage is skipped |
| `HOST`, `PORT` | Only read in HTTP transport mode; the local server runs over stdio |

FlightClaw reads no other environment variable, writes only to its own `data/`
directory, and runs no install-time script.

## License

MIT — see [LICENSE](LICENSE).