Open-source award flight search engine. Find the best way to use credit card points for flights — with a REST API, MCP server for Claude Desktop, and a step-by-step booking playbook engine.
Live App · API Docs · MCP Setup
PointPilot searches across airline loyalty programs to find award flights, then tells you exactly how to book them:
- Search — Enter your origin, dates, and points balances. PointPilot checks award availability across programs (Aeroplan, ANA, Virgin Atlantic, etc.) and compares against cash prices.
- Rank — Results are scored by cents-per-point (CPP) value, cash savings, transfer path availability, and booking friction.
- Playbook — Select a flight and get step-by-step transfer and booking instructions, including risk warnings (low seats, slow transfers, expiring promos).
| Program | Code |
|---|---|
| Amex Membership Rewards | MR |
| Chase Ultimate Rewards | CHASE |
| Capital One Miles | CAP1 |
| Citi ThankYou Points | CITI |
| Bilt Rewards | BILT |
| Marriott Bonvoy | MARRIOTT |
git clone https://github.com/wrahim3933/PointPilot.git
cd PointPilot/backend
pip install -r requirements.txtcp .env.example .env
# Edit .env — no API keys needed for basic functionality (mock providers work out of the box)uvicorn app.main:app --reload --port 8000The API is now running at http://localhost:8000. Try it:
# Health check
curl http://localhost:8000/health
# Search for award flights from JFK in July
curl -X POST http://localhost:8000/v1/trip-searches \
-H "Content-Type: application/json" \
-d '{
"origins": ["JFK"],
"date_window_start": "2025-07-01",
"date_window_end": "2025-07-15",
"duration_nights": 5,
"travelers": 2,
"cabin_preference": "business",
"search_mode": "points",
"balances": [{"program": "MR", "balance": 150000}, {"program": "CHASE", "balance": 80000}]
}'PointPilot includes an MCP server so you can search flights and get playbooks directly from Claude.
1. Install uv (if you don't have it):
brew install uv # macOS
# or: curl -LsSf https://astral.sh/uv/install.sh | sh2. Add to Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"pointpilot": {
"command": "uv",
"args": [
"run", "--with", "mcp[cli]", "--with", "requests",
"python", "/path/to/PointPilot/backend/mcp_server.py"
],
"env": {
"POINTPILOT_API_BASE": "https://pointpilot-api.up.railway.app"
}
}
}
}Update the path to where you cloned the repo. For local development, change
POINTPILOT_API_BASEtohttp://localhost:8000.
3. Restart Claude Desktop. The tools appear automatically.
| Tool | Description |
|---|---|
search_award_flights |
Find award flights from any origin, ranked by value |
generate_booking_playbook |
Get step-by-step transfer and booking instructions |
get_featured_deals |
See curated award deals available right now |
get_transfer_partners |
Explore transfer partners and active bonuses for any program |
Example prompt:
"Find me business class flights from JFK to Tokyo using my 150k MR points"
| Method | Path | Description |
|---|---|---|
POST |
/v1/trip-searches |
Create a new trip search |
GET |
/v1/trip-searches/{id} |
Retrieve a trip search |
| Method | Path | Description |
|---|---|---|
POST |
/v1/recommendations/generate |
Generate ranked award flight options |
| Method | Path | Description |
|---|---|---|
POST |
/v1/playbook/generate |
Generate booking playbook from a recommendation |
POST |
/v1/playbook/generate-from-match |
Generate playbook from raw flight params |
POST |
/v1/playbook-ai/explain-step |
AI explanation for a playbook step |
| Method | Path | Description |
|---|---|---|
GET |
/v1/featured-deals |
Current featured award deals |
POST |
/v1/outcomes |
Record a booking outcome |
GET |
/health |
Health check |
backend/
├── mcp_server.py # MCP server for Claude Desktop (stdio)
├── app/
│ ├── main.py # FastAPI entry point
│ ├── store.py # JSON file persistence
│ ├── routers/ # HTTP endpoints
│ ├── services/ # Business logic
│ │ ├── recommender.py # Destination candidate generation
│ │ ├── scoring.py # Blended value scoring
│ │ ├── valuation.py # CPP range & confidence calculation
│ │ ├── risk.py # Booking risk assessment
│ │ ├── transfer_graph.py # Card → airline transfer paths
│ │ ├── playbook_service.py # Step-by-step playbook builder
│ │ └── ai/ # AI explanation engines (mock / Claude)
│ ├── adapters/
│ │ ├── providers.py # Award & airfare data providers
│ │ └── interfaces.py # Provider protocol definitions
│ ├── domain/
│ │ └── models.py # Pydantic models
│ └── data/ # Static transfer partner & airline data
├── data/ # Runtime data (deals, snapshots)
└── scripts/ # Data pipeline scripts
Each award option is scored on three axes:
- CPP Value — cents per point, computed as
(cash_price - taxes) / points_cost. Capped at 7.5 cpp to prevent outliers. - Out-of-Pocket Cost — total cash the traveler actually pays (taxes on award, or full fare in cash mode).
- Friction — penalty for stops, long travel times, and complex itineraries.
These are combined into a blended score weighted by the user's preference (maximize_value, minimize_cost, or balanced).
The playbook explanation endpoint supports two providers:
# Default — deterministic, no API key needed
AI_PROVIDER=mock
# Claude Sonnet — requires ANTHROPIC_API_KEY
AI_PROVIDER=claudeOut of the box, PointPilot uses estimated/mock data that works without API keys. For live data:
| Source | What It Provides | Env Var |
|---|---|---|
| Seats.aero | Live award seat availability | SEATS_AERO_API_KEY |
| Duffel | Live cash airfare pricing | DUFFEL_API_KEY |
| Anthropic | AI playbook explanations | ANTHROPIC_API_KEY |
Contributions welcome! Some areas that could use help:
- More transfer partner data — adding new programs or updating transfer ratios
- Better destination coverage — expanding the route candidate pool
- Scoring improvements — refining the CPP/friction/value model
- New MCP tools — hotel search, multi-city routing, etc.
# Run locally
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# Test MCP server
mcp dev backend/mcp_server.pyMIT — see LICENSE.