Real-time flight search in Python, wired into Claude Code via MCP — the starter kit for AI-powered travel planners.
Quickstart · Features · Architecture · Roadmap · Italiano
AgentVoli is an open-source toolkit that turns the unofficial Google Flights API into a working AI travel planner, ready to plug into Claude Code via the Model Context Protocol (MCP).
Out of the box you get:
- 🔎 Real-time flight search powered by Google Flights (round-trip, one-way, multi-city)
- 🤖 MCP server pre-wired — Claude calls
search_flights,search_dates,find_airportsas native tools - 📅 Weekend scanner — finds the cheapest short-haul return from multiple Italian airports
- 🌍 Route matrix scripts — built-in examples (e.g. Rome → Malta, Italy → Europe weekend trips)
- 💸 Free-tier API recipes — Open-Meteo, Geoapify, Nominatim, Ticketmaster, Groq + a
.env.examplemapping every key needed to grow into a full AI-powered travel planner
Think of it as the "hello world" your Marrakech-on-a-budget agent has been waiting for.
git clone https://github.com/uppifyagency/AgentVoli.git
cd AgentVoli
uv sync # installs the flights Python library + the MCP serverNo
uv? Usepip install -e ".[mcp]"(orpipx install flightsfor the CLI only).
uv run python agentvoli_malta.pyOutput (live data, prices vary):
Scansione 12 combinazioni FCO <-> MLA (andata e ritorno)...
2026-06-03 -> 2026-06-09: 83 opzioni, min EUR 65
...
TOP 12 OFFERTE ROMA (FCO) <-> MALTA (MLA)
================================================================================
1. EUR 65
Andata: Wed 03-Jun 17:00 -> 18:25 AZ 884 (1h25m, diretto)
Ritorno: Tue 09-Jun 20:40 -> 22:15 FR 8561 (1h35m, diretto)
Open this project in Claude Code — the bundled .mcp.json registers the flight-search MCP server automatically. Approve it once and Claude gets first-class flight-search tools (search_flights, search_dates, find_airports).
Direct access to Google Flights data through reverse-engineered endpoints — no API key, no rate-limited free tier, no paid plan. Round-trip, one-way, multi-city, premium cabins, alliance filters, per-flight booking deep-links.
Drop the bundled MCP server into Claude Code, Claude Desktop, Cursor, or any other STDIO-MCP client. Your AI agent now searches real flights without a single line of glue code.
Working scripts for the patterns Italian travelers actually search:
| Script | What it does |
|---|---|
agentvoli_malta.py |
Rome (FCO) ⇄ Malta (MLA) round-trip matrix, today/tomorrow + 6 return dates |
agentvoli_weekend_scan.py |
Saturday → Sunday weekend escape from Pisa/Florence/Bologna to 14 European cities, ≤3h flight |
agentvoli_rerun_missing.py |
Rate-limit-aware retry of the routes Google throttled in the first pass |
.env.example maps every free-tier key needed to grow into a full travel planner: weather, restaurants, points of interest, events, FX rates, destination imagery, LLM orchestration. No paid SerpAPI or Amadeus required.
All scripts compute date.today() at runtime — no more hard-coded dates that rot after a week.
┌────────────────────────┐
│ Claude Code │
│ (or Claude Desktop / │
│ Cursor / any MCP) │
└──────────┬─────────────┘
│ MCP / stdio
▼
┌────────────────────────┐ ┌─────────────────────┐
│ Flight Search MCP │ ───► │ Google Flights │
│ (FastMCP) │ │ (reverse-engineered│
│ │ ◄─── │ protobuf API) │
└──────────┬─────────────┘ └─────────────────────┘
│
▼
┌────────────────────────┐
│ AgentVoli scripts │
│ - malta.py │
│ - weekend_scan.py │
│ - rerun_missing.py │
└──────────┬─────────────┘
│
▼ (future)
┌────────────────────────────────────────────────────────┐
│ Free-tier travel APIs (see .env.example) │
│ Open-Meteo · Geoapify · Nominatim · Ticketmaster │
│ Foursquare · OpenTripMap · Pexels · open.er-api.com │
└────────────────────────────────────────────────────────┘
The end-goal: a prompt like "Rome → Marrakech, 21–24 May, €300 budget, flights + hotel + experiences" yields a complete itinerary with real prices, Google-Places restaurant picks, and a day-by-day plan that fits the budget.
| Component | Status | Notes |
|---|---|---|
| ✅ shipped | Google Flights via Python | |
| 🤖 Claude Code MCP integration | ✅ shipped | .mcp.json |
| 🇮🇹 Italian route examples | ✅ shipped | Malta, weekend short-haul |
| ☀️ Weather (Open-Meteo) | 🟡 next | zero-key, what-to-pack agent |
| 📍 POIs & restaurants (Geoapify) | 🟡 next | free 3k req/day |
| 💱 Multi-currency budget | 🟡 next | open.er-api.com, keyless |
| 🏨 Hotel pricing | 🔴 hard | no real free API — Booking.com affiliate links as fallback |
| 🎟️ Activities & events | 🟡 planned | Ticketmaster + OpenTripMap |
| 🧠 LLM orchestrator | 🟡 planned | Groq / Gemini Free tier for $0 ops |
A curated set of free-tier APIs perfect for AI travel agents. Full setup in .env.example.
| API | Free tier | Card required? | Use case |
|---|---|---|---|
| Open-Meteo | unlimited | no | weather forecast |
| Nominatim (OSM) | 1 req/sec | no | geocoding |
| Geoapify Places | 3,000 req/day | no | POIs, restaurants, isochrones |
| OpenTripMap | 5,000 req/day | no | tourist attractions |
| Foursquare Places | 950 req/day | no | restaurant data |
| Ticketmaster Discovery | 5,000 req/day | no | live events |
| REST Countries | unlimited | no | country metadata |
| open.er-api.com | unlimited | no | FX rates |
| Pexels | unlimited | no | destination images |
| Google Places (New) | $200/month credit | yes | premium POI data |
| Groq / Gemini Free | generous free tier | no | LLM orchestration |
from datetime import date, timedelta
from fli.models import Airport, FlightSearchFilters, FlightSegment, MaxStops, PassengerInfo, SeatType, SortBy, TripType
from fli.search import SearchFlights
tomorrow = (date.today() + timedelta(days=1)).isoformat()
filters = FlightSearchFilters(
trip_type=TripType.ONE_WAY,
passenger_info=PassengerInfo(adults=1),
seat_type=SeatType.ECONOMY,
stops=MaxStops.NON_STOP,
sort_by=SortBy.CHEAPEST,
flight_segments=[FlightSegment(
departure_airport=[[Airport.FCO, 0]],
arrival_airport=[[Airport.MLA, 0]],
travel_date=tomorrow,
)],
)
for flight in SearchFlights().search(filters)[:5]:
print(f"EUR {flight.price:.0f} {flight.legs[0].airline.name} {flight.legs[0].flight_number}")AgentVoli è il toolkit open-source per la ricerca voli in tempo reale direttamente da Python e da Claude Code via MCP. Sfrutta endpoint Google Flights non ufficiali per ottenere prezzi, orari e disponibilità senza chiavi API a pagamento.
- 🔎 Ricerca voli Google (FCO, MXP, BGY, CTA, NAP, e tutti gli aeroporti supportati) con prezzi reali e tempi di volo
- 📅 Scan del weekend — trova i voli short-haul più economici dall'Italia (Pisa, Firenze, Bologna) verso 14 capitali europee, andata sabato e ritorno domenica sera
- 🤖 Agente voli per Claude Code — il server MCP è già configurato in
.mcp.json, basta lanciare Claude e approvare - 🇲🇹 Esempio Roma → Malta completo, con matrice andata/ritorno dinamica
- Clona il repo e installa con
uv sync - Lancia
uv run python agentvoli_malta.pyper vedere i voli FCO ⇄ MLA reali di oggi - Apri il progetto in Claude Code → l'agente AI ora cerca voli direttamente
L'obiettivo è far diventare AgentVoli un planner di viaggio AI in stile "voglio andare da Roma a Marrakech, 4 giorni, budget 300 €" — l'agente compone voli + hotel + ristoranti (via Google Places) + esperienze, rispettando il budget. Vedi la roadmap per lo stato dei pezzi mancanti.
MIT — do what you want, attribution appreciated.
Third-party dependencies retain their own licenses; respect them when redistributing.
Built with
If AgentVoli saved you from clicking through Google Flights 47 times, drop a star ⭐