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, or add {"mcpServers":{"flightclaw":{"url":"https://mcp.flightclaw.com/mcp"}}} to ~/.cursor/mcp.json
VS Code	One-click install, 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 server, giving any MCP-compatible client (Claude Code, Claude Desktop, etc.) access to flight search and tracking tools.

Setup

# 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:

{
  "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/:

# 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)

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)

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 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.