🌍 Wander Agent

Your AI's personal travel agent — flights, hotels, visas, points & miles.

66 tools. Zero API keys. One line to install.

Ask your AI anything about travel and get real data back, not hallucinations — live flight prices, the cheap fares airlines hide, real visa rules, 16-day forecasts, and credit-card points sweet spots.

pip install wander-agent

See the launch demo · ⭐ Star this repo if it saves you a layover ✈️

Real run: asked for "every way to save money on DXB→DPS for 4" — it surfaced hidden-city, split-ticket, and nearby-airport fares for ~$8,000 group savings.

---

Try these the second you install — paste any of them to your AI:

• 🛫 "Find me a flight from NYC to Tokyo the airlines don't want me to see." → hidden-city + split-ticket fares OTAs are banned from showing you
• 🌴 "Plan a 10-day Bali trip for 2 from Dubai in September, budget $3,000." → flights, hotels, visa, weather, restaurants, packing list, day-by-day — one response
• 🛂 "Which of my two passports gets me into more countries visa-free?" → dual-passport diff with Henley rankings
• 💳 "Turn my Amex points into the best business-class flight to Europe." → points sweet-spot finder across transfer partners

---

What is this?

Wander Agent is a tool plugin for AI assistants (Claude, Cursor, Windsurf, etc.) that gives the AI real travel data to work with.

Without this plugin, asking an AI "cheapest flights from New York to Tokyo in August?" gets you a made-up answer. With this plugin, the AI calls real data sources — Google Flights, Open-Meteo, US State Dept advisories, OpenStreetMap — and gives you actual prices, real forecasts, and live visa requirements.

You talk to the AI the same way you always do. The AI does the rest.

"Plan me a 10-day trip to Bali for 2 people leaving from Dubai in September, budget $3,000" → Real flights, real hotels, visa requirements, weather forecast, local restaurants, packing list, day-by-day itinerary — all in one response.

---

What can it do?

• Search live flights (Google Flights + Kiwi.com in parallel)
• Find hidden-city fares — e.g. buy NYC→Mexico via Houston, exit in Houston at 40% discount
• Split-ticket search — book two separate tickets via a hub; OTAs are contractually forbidden from showing you this
• Month-level price scan — check every month for the next year, returns cheapest month to fly
• Fare calendar — cheapest day within a given month, day-of-week analysis
• Scan for mistake fares and error pricing from deal alert sites
• Find the cheapest destination you can fly to from anywhere
• Find cheapest meeting point for friends flying from different cities
• Automatically checks nearby airports (JFK also checks EWR, LGA; DXB also checks SHJ, AUH)

• Search hotels with direct booking links to Booking.com, Airbnb, Expedia, Tripadvisor, and 6 more
• Optimize for cheapest flight + hotel combo across flexible dates

• Check if you need a visa, e-visa, ETA, or nothing at all
• See every country you can enter without a full visa
• Passport power ranking — Henley Index 2024 rank, visa-free %, regional breakdown
• Dual-passport comparison — see exactly which destinations each passport unlocks that the other doesn't
• Transit visa check — do you need a visa just to change planes? 200+ passport × layover rules
• Official government apply links included

• 16-day live forecast for any location
• Best month to visit anywhere based on 5 years of climate data
• Jet lag calculator with science-based recovery schedule

• Live US State Dept advisory level for any country (1 = safe, 4 = do not travel)
• List every country at or above a given risk level
• Recent travel news: strikes, airport closures, entry bans, protests

• Daily budget estimates for 220 cities (budget / mid-range / luxury)
• Live currency conversion
• Total trip cost estimate combining flights, hotels, and daily spend

• Day-by-day itinerary with weather and activities for each day
• Rank and score destinations by cost + weather + safety + events
• Compare multiple destinations side-by-side
• Aurora viewing destinations with NOAA KP-index forecast
• Open-jaw trips — fly into Rome, train to Paris, fly home from Paris. Composed automatically.

• Restaurants, bars, pubs, and cafes near any location (OpenStreetMap)
• Cuisine filters, price level, opening hours, distance
• Booking links: Google Maps, Zomato, TripAdvisor, Yelp, OpenTable, Resy, Untappd

• Packing list tailored to weather, activities, and trip length
• Language phrasebook for 17 languages with pronunciation guides
• Layover guide for 10 major hub airports (DXB, SIN, IST, DOH, NRT, CDG, HKG, ICN, AMS, HND)
• Health requirements: vaccines, water safety, food safety, pre-trip timeline
• Bus, train, and ferry options with direct booking links
• Viewpoints, beaches, hiking trails, coworking spaces near any location
• Local SIM guide — 25+ countries: best prepaid SIM vs eSIM, cost, where to buy, tethering policy

• Saves your home airports, passports, currency, and interests — never ask again
• Logs your trip history
• Saved trips — a persistent trip with an 8-item booking checklist that survives across sessions
• Fare watching — set a target price on a route, re-price on demand, get a buy signal when it drops
• Value ranking — scores options 0–100 on price plus stops, duration, refundability, baggage and hassle (flags hidden-city / split-ticket risk), so cheapest isn't blindly "best"

• Points valuation — is this award booking a good deal? Cents-per-point calculator with verdict (excellent / good / fair / poor) against 20+ program baselines
• Transfer partners — which airlines and hotels can you transfer Chase UR / Amex MR / Citi TYP / Capital One / Bilt points to? With ratios and transfer times
• Points vs cash — should you use points or pay cash? Factors in cpp value, opportunity cost, and what you'd earn back paying cash
• Earning calculator — how many points does a $500 dinner earn on your Amex Gold? 9 cards modeled with bonus categories
• Sweet spot awards — curated list of outsized-value redemptions: ANA first class for 120k VA miles (16.7cpp), Hyatt all-inclusive for 25k (2.4cpp), Turkish business for 45k (8.9cpp)
• Program comparison — which of your points programs gives the best value for a specific booking?
• Card portfolio — save your cards to your profile, points tools use them automatically

---

Setup (5 minutes)

Step 1 — Install Python

You need Python 3.10 or newer. Check if you have it:

python3 --version

Don't have it? Download from python.org.

---

Step 2 — Install Wander Agent

From PyPI (recommended):

pip install wander-agent

Or with uv — no install at all, run directly:

uvx wander-agent

Or from source:

git clone https://github.com/VirajMishra1/wander-agent.git
cd wander-agent
pip install -e .

Verify it worked:

wander-agent --help

---

Step 3 — Connect to your AI

Pick the app you use:

Open this file in a text editor:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Save the file, then quit and reopen Claude Desktop.

If you get an error about wander-agent not being found, find the full path first:

which wander-agent

Then use that path in the config:

{
  "mcpServers": {
    "wander-agent": {
      "command": "/usr/local/bin/wander-agent"
    }
  }
}

claude mcp add wander-agent wander-agent

Confirm it registered:

claude mcp list

Create or edit .cursor/mcp.json in your home directory:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Restart Cursor.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Restart Windsurf.

Open VS Code settings, search for "Cline MCP", edit cline_mcp_settings.json:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Edit .continuerc.json in your project or home directory:

{
  "mcpServers": [
    {
      "name": "wander-agent",
      "command": "wander-agent"
    }
  ]
}

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "wander-agent": {
      "command": {
        "path": "wander-agent",
        "args": []
      }
    }
  }
}

---

Optional: API keys for better data

Everything works without any API keys. These add richer data if you want:

Variable	What it unlocks	Get it free at
FOURSQUARE_API_KEY	Real ratings and price levels for restaurants/bars	foursquare.com/developers
TICKETMASTER_API_KEY	Live event listings (concerts, sports, shows)	developer.ticketmaster.com

Set them before starting your AI:

export FOURSQUARE_API_KEY=your_key_here
export TICKETMASTER_API_KEY=your_key_here

Or add them to your shell profile (~/.zshrc, ~/.bashrc) to make them permanent.

---

All 66 Tools

✈️ Flights

Tool	What it does
search_flights	Live flight search across Google Flights and Kiwi.com in parallel. Returns prices, duration, stops, and booking links.
find_skiplagged_fares	Hidden-city fares — buy a connecting flight and exit at the layover city. Often 40–60% cheaper. Carry-on only.
find_split_ticket	Book two separate tickets through a hub instead of one through-ticket. OTAs are contractually forbidden from showing this. Savings of 20–60% on many routes. Includes full risk disclosure.
find_cheapest_month	Scans the next 12 months by sampling the first Tuesday of each month (statistically cheapest booking day). Returns all months ranked by price with season analysis and booking links.
fare_calendar	Full month price grid — up to 15 sampled days, day-of-week analysis, price tiers, best/worst weeks. Find the cheapest day to fly within a given month.
find_mistake_fares	Scans Secret Flying and The Flight Deal RSS for error fares and flash deals.
cheap_anywhere_from	Cheapest destinations from an origin across 114 airports worldwide.
find_destinations_by_budget	Finds destinations reachable within a total budget (flights + hotels).
multi_origin_meetup	Cheapest city for multiple friends to meet, flying from different cities.
verify_flight_route	Confirms a direct or connecting route exists between two airports.
find_aurora_destinations	Aurora-viewing destinations with live NOAA KP-index forecast and flight prices.

🏨 Hotels

Tool	What it does
search_hotels	Hotels with booking links to Booking.com, Airbnb, Expedia, Tripadvisor, and 6 more.
optimize_budget	Finds the cheapest flight + hotel combo across a flexible date window (±7 days).

📋 Visas & Entry

Tool	What it does
check_visa_requirement	Visa category for a passport + destination pair. Returns visa-free, ETA, e-visa, visa on arrival, or visa required — with the official apply link.
visa_free_destinations	Every country a given passport can enter without a full embassy visa.
get_passport_power	Henley Index 2024 rank, visa-free access count, frictionless travel %, and regional breakdown for any passport. Pass two passports to get a head-to-head diff: exactly which destinations each one unlocks that the other doesn't.
check_transit_visa	Do you need a transit visa at your layover airport? Covers 200+ passport × layover-country combinations. Checks LHR, JFK, DXB, SIN, FRA, IST, DOH, NRT, ICN, YYZ, SYD, and 30+ others.

🌤️ Weather

Tool	What it does
get_weather	16-day live weather forecast for any coordinates. Falls back to 5-year historical data for dates beyond the forecast window.
best_month_to_visit	Ranks all 12 months for a location by weather quality, based on historical climate data.

⚠️ Safety & News

Tool	What it does
get_travel_advisory	US State Dept advisory level (1–4) and summary. Pulled from the live RSS feed.
list_advisories_by_level	All countries currently at or above a given advisory level.
get_travel_news	Scans Google News for recent disruptions: strikes, airport closures, entry bans, protests.

💰 Costs & Currency

Tool	What it does
get_cost_of_living	Daily budget estimates for 220 cities across budget, mid-range, and luxury tiers.
convert_currency	Live currency conversion via European Central Bank rates.
get_exchange_rates	Exchange rates for multiple currencies from a base currency.

🗺️ Planning & Scoring

Tool	What it does
plan_trip_package	The main orchestrator. Calls 8+ tools in parallel and returns a complete trip: flights, hotels, visa, weather, safety, activities, ground transport, cost estimate, and booking checklist.
plan_itinerary	Day-by-day itinerary with weather forecast and suggested activities for each day.
find_open_jaw	Plan a fly-in/overland/fly-out trip: land in city A, travel by train or bus, fly home from city B. Composes flight + ground transport search. Shows total cost vs a round-trip to city A only. Accepts city names or IATA codes.
score_destinations	Ranks destinations by a weighted combination of cost, weather, safety, and events.
compare_destinations	Side-by-side comparison of 2–5 destinations for the same dates.

🍜 Food & Nightlife

Tool	What it does
search_restaurants_bars	Real venues near a location from OpenStreetMap. Returns cuisine, price level, opening hours, distance, and links to Google Maps, Zomato, TripAdvisor, Yelp, OpenTable, Resy, and Untappd.

🌐 Smart Trip Tools

Tool	What it does
score_nomad_cities	Ranks cities for remote work across 6 dimensions: cost, safety, internet speed, weather, visa ease, and lifestyle. Configurable weights.
calculate_flight_carbon	CO2e footprint for any flight using ICAO/DEFRA 2024 factors with radiative forcing (RFI ×1.9). Per-passenger and total emissions, Gold Standard offset cost, and train/car comparison for short routes.

🎒 On the Ground

Tool	What it does
generate_packing_list	Packing list tailored to destination weather, activities, trip length, and budget level.
find_places	Viewpoints, beaches, hiking trails, coworking spaces, waterfalls, markets, and more from OpenStreetMap.
calculate_jet_lag	Jet lag severity with a science-based recovery schedule: pre-departure shift, melatonin timing, light exposure strategy.
get_language_phrasebook	Phrasebook for 17 languages with local script, romanized pronunciation, and audio tips.
get_stopover_guide	What to do during a layover at 10 major hubs. Includes transit visa check, in-airport activities, and city excursion options.
check_travel_health	Required and recommended vaccines, water safety, food safety, mosquito risk, altitude risk, and a pre-trip preparation timeline. Based on CDC and WHO 2024–2025 data.
search_ground_transport	Bus, train, and ferry options with booking links. Region-aware: Amtrak and Greyhound for the US, Trainline and BlaBlaCar for Europe, IRCTC for India, 12Go for Southeast Asia.
get_local_sim_guide	Best prepaid SIM card and eSIM for 25+ countries. Returns operator, cost, data allowance, where to buy, tethering policy, and duration-based advice (≤3 days → eSIM; longer → local SIM). Falls back to Airalo/Holafly for unlisted countries.

🏛️ Attractions & Info

Tool	What it does
search_activities	Attractions near a location from Wikidata. Filter by category: museums, parks, architecture, nightlife, food, historic, nature, and more.
get_local_events	Live events from Eventbrite: concerts, sports, festivals.
get_destination_info	Country basics: currency, official language, timezone, dialling code, driving side.
geocode	Converts a place name to coordinates.
verify_place	Confirms a place actually exists (catches AI hallucinations before they reach you).

🧠 Traveler Profile

Tool	What it does
get_traveler_profile	Loads your saved profile: home airports, passports, currency, interests, and trip history.
onboard_traveler	One-time setup. Saves your preferences so the AI uses them automatically in every future session.
update_traveler_profile	Update any field, manage credit cards in your portfolio, or log a completed trip.
get_trip_history	Your logged trip history.

🧳 Saved Trips (cross-session memory)

Persisted to ~/.wander_agent/trips.json. A trip carries an 8-item booking checklist (flights, hotel, visa, insurance, ground transport, advisory, packing, notify bank).

Tool	What it does
save_trip	Save a trip you're planning. Returns a trip_id and a fresh booking checklist.
list_my_trips	List saved trips with checklist progress. Filter by status (planning/booked/completed/cancelled).
get_trip_status	Full state + checklist progress for one trip, by id or destination.
update_trip	Change status/dates, tick checklist items, or shortlist a flight/hotel option onto the trip.
delete_trip	Remove a saved trip.

🔔 Fare Watching

Persisted to ~/.wander_agent/fare_watches.json. Records a baseline price and a price history per watched route.

Tool	What it does
watch_fare	Start watching a route with an optional target price. Captures a baseline on creation.
list_fare_watches	List watches with baseline / last / lowest price seen and status.
check_fare_watches	Re-price watched routes now. Returns buy-signal alerts: target_hit, price_drop, price_rise, no_change.
stop_fare_watch	Pause or delete a watch.

⚖️ Value Ranking

Tool	What it does
rank_trip_options	Scores a list of flight/trip options 0–100 on price plus stops, duration, refundability, baggage and hassle. Presets: cheapest / fastest / easiest / flexible / balanced. Flags hidden-city, split-ticket and self-transfer risk so the cheapest fare isn't blindly the winner.

💳 Credit Card Points & Miles

Static dataset covering 20 loyalty programs (Chase UR, Amex MR, Citi TYP, Capital One, Bilt, 11 airlines, 4 hotel chains), 9 popular credit cards with bonus categories, and 10 curated sweet-spot awards. Card portfolio saved to ~/.wander_agent/profile.json.

Tool	What it does
estimate_points_value	Is this award booking worth it? Calculates cents-per-point and compares against baseline valuations for the program. Returns excellent / good / fair / poor verdict.
find_transfer_partners	Shows all airline and hotel transfer partners for a bank program (Chase UR → United, Hyatt, BA, etc.) with transfer ratios and times. Sorted by partner value.
calculate_points_or_cash	Should you use points or pay cash for this booking? Factors in cpp value, opportunity cost of points, and how many points you'd earn back paying cash on a specific card.
estimate_points_earning	How many points a purchase earns on a given card. Covers 9 cards with bonus category multipliers (3x dining, 5x travel portal, 4x supermarkets, etc.).
find_sweet_spot_awards	Curated high-value redemptions: ANA first class via VA miles (16.7cpp), Singapore Suites (16.3cpp), Turkish business (8.9cpp), Hyatt all-inclusive (2.4cpp), and more. Filters by your programs, cabin, budget, or route.
compare_points_programs	Which of your points programs gives the best value for a specific booking? Compares estimated points cost, portal vs transfer value, best partner, and matching sweet spots. Uses your profile cards automatically.

---

Tool Rankings: Usefulness × X-Factor

Ranked by a combination of practical impact and uniqueness — things no OTA, no chatbot, and no other travel tool does.