flightclaw
Search Google Flights, price-track routes and get alerts when fares drop, then book and pay through Duffel. Remembers travellers, companions
Open source Open in the app JSON README (API)
About
Search Google Flights, price-track routes and get alerts when fares drop, then book and pay through Duffel. Remembers travellers, companions, loyalty programmes, cards and cabin preferences so options come back ranked for the person asking.
Details
- Kind
- Plugins
- Topic
- Cloud & DevOps
- Publisher
- jackculpan
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Stars
- 71
- Forks
- 12
- Open pull requests
- 1
- Last push
- 2026-09-02T21:17:16Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-03 02:00:26
- Updated
- 2026-09-03 02:00:26
- Origin id
jackculpan/flightclaw
README
# flightclaw
Track flight prices from Google Flights. Search routes, monitor prices over time, and get alerts when prices drop.
## 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/flightclaw/server.py
```
Or in Claude Desktop, add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"flightclaw": {
"command": "python3",
"args": ["/path/to/flightclaw/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 jackculpan/flightclaw
```
## Install (Grok)
```
/plugin marketplace add xai-org/plugin-marketplace
/plugin install flightclaw
```
## Install (Claude Code)
```
/plugin marketplace add jackculpan/flightclaw
/plugin install flightclaw@flightclaw
```
## Install (Cursor)
```
/plugin marketplace add jackculpan/flightclaw
/plugin install flightclaw
```
## Install (Gemini CLI)
```bash
gemini extensions install https://github.com/jackculpan/flightclaw
```
Each client reads its own manifest from this repo — `.grok-plugin/`,
`.claude-plugin/`, `.cursor-plugin/` and `gemini-extension.json` — and they all
start the same MCP server.
## The connector
The connector 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 connector 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 connector 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).