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

Terminal

pip install wander-agent

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

Wander Agent finding hidden-city and split-ticket fares the airlines hide

_{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?

✈️ Flights

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)

🏨 Hotels

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

📋 Visas & Entry

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

🌤️ Weather

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

⚠️ Safety

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

💰 Costs

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

🗺️ Planning

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.

🍜 Food & Nightlife

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

🎒 On the Ground

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

🧠 Memory & Decisions

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"

💳 Credit Card Points & Miles

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:

bash

python3 --version

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

Step 2 — Install Wander Agent

From PyPI (recommended):

Terminal

pip install wander-agent

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

bash

uvx wander-agent

Or from source:

bash

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

Verify it worked:

bash

wander-agent --help

Step 3 — Connect to your AI

Pick the app you use:

Claude Desktop

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:

config.json

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

bash

which wander-agent

Then use that path in the config:

config.json

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

Claude Code (terminal)

Terminal

claude mcp add wander-agent wander-agent

Confirm it registered:

Terminal

claude mcp list

Cursor

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

config.json

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

Restart Cursor.

Windsurf

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

config.json

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

Restart Windsurf.

Cline (VS Code extension)

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

config.json

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

Continue.dev

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

config.json

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

Zed

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

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

server.ts

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.

Rank	Tool	Why it's here
🥇 1	`find_split_ticket`	OTAs are contractually prevented from showing this. Book two tickets via a hub instead of a through-ticket. 20–60% savings on many long-haul routes. The travel industry's open secret.
2	`find_skiplagged_fares`	Hidden-city ticketing. Buy a flight to city B with a layover in city A — exit in city A and never board the last leg. 40–60% off. Illegal per airline T&Cs but not against any law. Carry-on only.
3	`plan_trip_package`	One message → complete trip. Fires 8+ tools in parallel: flights, hotels, visa, weather, safety, activities, ground transport, cost estimate. The single best demo of what this agent can do.
4	`find_cheapest_month`	Scans 12 months, samples first Tuesday of each (statistically cheapest booking day). Returns months ranked by price with season labels. Shifting by 1–2 months = hundreds of dollars saved.
5	`check_transit_visa`	The one nobody thinks to check until it's too late. Do you need a visa just to change planes at Heathrow? At Frankfurt? 200+ passport × layover combinations. Catches the trip-killer before you book.
6	`multi_origin_meetup`	Three friends, three different cities. What's the cheapest city for all of them to meet? No OTA has a tool for this.
7	`find_open_jaw`	Fly into Rome, take a train to Paris, fly home from Paris. No OTA lets you compose this. Automatically prices both flights + the overland segment and compares vs a simple round-trip to Rome.
8	`get_passport_power`	Henley 2024 rank, visa-free %, regional breakdown. Dual-passport mode: exact set-diff of which destinations each passport unlocks. "Use your Indian passport for Thailand, your US passport for Brazil."
9	`score_nomad_cities`	6-dimension scoring for digital nomad decisions: cost, safety, internet speed, weather, visa ease, lifestyle. Configurable weights. "Score Bali vs Lisbon vs Tbilisi for 3 months, weight internet 3× above cost."
10	`find_mistake_fares`	Error fares and airline pricing mistakes from dedicated deal aggregators. Passive discovery — "are there any crazy cheap fares out of JFK right now?"
11	`fare_calendar`	Full price grid for a month. Up to 15 sampled days, cheapest day highlighted, day-of-week analysis (Tuesdays 18% cheaper on average), best/worst weeks.
12	`cheap_anywhere_from`	"Where can I fly cheapest from London right now?" Scans 114 airports. Discovery tool for spontaneous travelers.
13	`find_destinations_by_budget`	"I have $1,500 total for 7 nights, leaving from NYC — where can I actually go?" Returns ranked reachable destinations.
14	`optimize_budget`	Shifts departure ±7 days to find the cheapest flight + hotel combo. Same trip, different dates, lower price.
15	`calculate_flight_carbon`	ICAO/DEFRA 2024 emission factors with radiative forcing (RFI ×1.9). Per-person and total CO2e, Gold Standard offset cost at $18/tonne, train/car comparison for routes under 1,500km.
16	`search_flights`	Core engine. Parallel Google Flights + Kiwi.com. Checks nearby airports automatically.
17	`check_visa_requirement`	Most-asked travel question. Instant answer with official government apply link.
18	`plan_itinerary`	Day-by-day schedule with weather per day and activity suggestions.
19	`score_destinations`	Weighted rank: cost + weather + safety + upcoming events. "Best place to go in September with good weather, under $150/day, safety level 1."
20	`visa_free_destinations`	Full list of countries a passport can enter without a full embassy visa.
21	`get_local_sim_guide`	25+ countries. Best prepaid SIM vs eSIM, exact cost, where to buy, tethering, activation steps. Short trip = eSIM. Long trip = local SIM. Saves the first-hour scramble at every airport.
22	`compare_destinations`	Side-by-side: cost, weather, safety, visa requirements, flights — for 2–5 destinations, same dates.
23	`search_ground_transport`	Bus + train + ferry with real booking links. Region-aware. Often cheaper and more convenient than flying for routes under 500km.
24	`check_travel_health`	Required vaccines, recommended vaccines, water safety, food safety, mosquito risk, altitude risk, pre-trip timeline. CDC + WHO 2025 data.
25	`get_travel_advisory`	Live US State Dept level 1–4 with summary. Pulled from RSS — not cached stale data.
26	`get_weather`	16-day live forecast. Falls back to 5-year historical climate data for further-ahead dates.
27	`find_aurora_destinations`	Best spots for northern lights with live NOAA KP-index forecast + flight prices from your origin. Viral for the "bucket list" audience.
28	`search_hotels`	Hotel search with deep links to 9 booking sites. No prices shown directly (all hotel price APIs are paid), but all the links you need.
29	`get_cost_of_living`	Daily budget for 220 cities: budget / mid-range / luxury tiers.
30	`best_month_to_visit`	Climate-based ranking of all 12 months for a location. Based on 5 years of historical data.
31	`get_stopover_guide`	What to actually do during a long layover at DXB, SIN, IST, DOH, NRT, CDG, HKG, ICN, AMS, or HND. In-airport options + city excursion feasibility.
32	`search_activities`	Wikidata attractions by category: museums, parks, architecture, food, nightlife, historic, nature.
33	`find_places`	OpenStreetMap viewpoints, beaches, hiking trails, coworking spaces, waterfalls, hot springs, markets.
34	`search_restaurants_bars`	Real venues from OSM with 7 booking site links per result. Cuisine filter, price level, distance.
35	`get_language_phrasebook`	17 languages. Local script + romanized pronunciation + audio tips.
36	`generate_packing_list`	Tailored to destination weather, planned activities, trip length, and budget level.
37	`get_local_events`	Live Eventbrite events at destination: concerts, festivals, sports. Best for 0–60 day horizon.
38	`get_travel_news`	Google News scan for disruptions: strikes, closures, protests, entry bans.
39	`calculate_jet_lag`	Severity rating + science-based recovery: pre-trip sleep shifting, melatonin timing, light exposure schedule.
40	`get_destination_info`	Country basics: currency, language, timezone, dialling code, driving side.
41	`list_advisories_by_level`	All countries currently at Level 2, 3, or 4. Useful for insurance and risk-screening.
42	`verify_flight_route`	Confirms a route actually exists. Catches hallucinated itineraries before you book.
43	`onboard_traveler`	One-time setup: home airports, passports, currency, interests. Feeds every tool automatically.
44	`get_traveler_profile`	Load saved profile. Used automatically at session start.
45	`update_traveler_profile`	Update preferences or log a completed trip.
46	`get_trip_history`	Your logged trip history.
47	`convert_currency`	ECB live rate conversion.
48	`get_exchange_rates`	Multi-currency rates from a base currency.
49	`geocode`	Place name → latitude/longitude. Used internally by most tools.
50	`verify_place`	Confirms a place exists before building a trip around it. Anti-hallucination guardrail.
51	`find_sweet_spot_awards`	Curated outsized-value redemptions the points community swears by. ANA first (16.7cpp), Singapore Suites (16.3cpp), Turkish J (8.9cpp). Filtered by your card portfolio.
52	`estimate_points_value`	Cents-per-point calculator with verdict against 20+ program baselines. Catches bad redemptions before you burn points.
53	`calculate_points_or_cash`	Points or cash? Factors cpp, opportunity cost, and earning-back. The question every points traveler asks on every booking.
54	`compare_points_programs`	Which program gives best value for this booking? Cross-program comparison with sweet-spot matching.
55	`find_transfer_partners`	Maps bank currency → airline/hotel partners. Transfer ratios, times, and partner valuations.
56	`estimate_points_earning`	Points earned per dollar by card and category. 9 cards modeled.

Data sources

Source	What it provides	Key needed?
Google Flights (scraper)	Flight prices and airline names	No
Kiwi.com	Live bookable flight prices	No
Open-Meteo	Weather forecast and 5-year historical climate	No
Frankfurter (ECB)	Currency exchange rates	No
Wikidata SPARQL	Attractions and points of interest	No
OpenStreetMap Overpass	Restaurants, bars, beaches, viewpoints, hiking	No
US State Dept RSS	Travel advisories	No
Open-Meteo Geocoding	Coordinates for place names	No
RESTCountries	Country metadata	No
Secret Flying / The Flight Deal	Mistake fares and deals	No
NOAA Space Weather	Aurora KP-index forecast	No
Google News RSS	Travel disruption news	No
Skiplagged	Hidden-city fares	No (fragile scraper)
Rome2Rio / Omio	Ground transport options	No (fallback to deeplinks)
Eventbrite	Live local events	No
Foursquare Places v3	Restaurant/bar ratings and price levels	Optional (free tier)
Ticketmaster Discovery	Live event listings	Optional (free tier)
Static datasets	Visa requirements, cost of living, airport data, transit visa rules, SIM card data, Henley rankings, points/miles valuations	N/A

How much can you trust each number?

Most results carry a data_meta block so the AI can tell you how reliable a figure is before you book:

json

"data_meta": {
  "confidence": "scraped_live",
  "trust_score": 80,
  "trust_label": "Live scrape",
  "meaning": "Scraped from Google Flights just now. Real but can shift minute to minute.",
  "fetched_at": "2026-06-02T18:30:00+00:00",
  "source": "google_flights + kiwi.com"
}

Label	Trust	What it means
`deeplink`	95	Opens the live provider page — always current
`live_api`	90	Official API (ECB rates, NOAA)
`live_rss`	85	Live government feed (State Dept advisories)
`live_forecast`	85	Open-Meteo live weather
`scraped_live`	80	Real-time scrape — real but volatile
`curated_snapshot`	55	Hand-curated dataset — verify before booking
`wikidata_fallback`	50	Wikidata-derived
`estimated`	35	Modeled figure — rough guide only

Honest limitations

Flight prices: Google Flights scraper can break if Google changes their page structure. Kiwi prices are real and bookable. Both run in parallel — if one fails the other still returns results.

Split-ticket risk: find_split_ticket surfaces real savings but carries missed-connection risk. If your first flight is delayed the second airline won't wait and won't rebook you. The tool always returns a full risk disclosure list. Buy travel insurance that covers missed connections on separate tickets.

Hotel prices: Every hotel price API is paid. This tool returns hotel names and links to 9 booking sites where you can see real prices. No prices are shown directly.

Visa data: Static snapshot (updated 2024). Policies change — always verify with the official link in the response before you book anything. Do not rely on this for immigration decisions.

Transit visa data: Rules encoded as a static dataset covering 200+ combinations. Edge cases (nationalities with bilateral exemptions, recent policy changes) may be missing. Always verify with the airline or destination embassy.

Passport power data: Henley Index 2024 snapshot. Rankings shift year to year. Confirm with official sources before making nationality-based decisions.

SIM card data: Curated snapshot as of 2024-Q4. Prices and plans change frequently. Treat as guidance; verify before purchase.

Events: Scraped from Eventbrite. Best coverage for events 0–60 days ahead. Further-future events may not be listed yet.

Travel advisories: US State Dept only. Updated within 24–48 hours of official changes via RSS.

Health data: Curated snapshot from CDC Yellow Book and WHO 2024–2025 recommendations. Not a substitute for advice from a travel medicine clinic.

Ground transport: Rome2Rio data for route discovery. Actual prices and schedules must be confirmed on the booking sites — times and fares change.

Points/miles valuations: Baseline cpp values are editorial averages (TPG, NerdWallet, OMAAT). Actual redemption value depends on specific award availability, transfer bonuses, and dynamic pricing. Sweet spot awards assume saver-level availability. Card bonus categories reflect terms as of 2025-Q1 — issuers change these periodically.

Carbon calculations: ICAO/DEFRA 2024 emission factors with standard RFI multiplier (×1.9). Actual emissions vary by aircraft type, load factor, and routing. Use as an estimate, not an accounting figure.

Cloud deployment (Docker)

The included Dockerfile and railway.toml let you host this server in the cloud so you can connect to it from any device — not just the computer where you installed it.

You do not need this for normal local use. Install and run locally as described in Setup above.

If you want to self-host on Railway:

bash

# Push to GitHub, then connect repo to Railway
# Set env vars in Railway dashboard if using optional API keys

The server switches from stdio (local) to HTTP automatically based on the WANDER_TRANSPORT environment variable.

Development

bash

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Count registered tools
grep -c "@mcp.tool()" src/wander_agent/server.py

Adding a tool:

Create src/wander_agent/tools/your_tool.py with an async function
Import it in src/wander_agent/server.py
Wrap with @mcp.tool() and an async wrapper function
Restart your AI client to pick up the new tool

CI: every push and PR to main runs the test suite on Python 3.10/3.11/3.12 and asserts the registered tool count.

Releases: publishing a GitHub release triggers the PyPI publish workflow (trusted publishing — no tokens). Bump version in pyproject.toml and server.json first.

License

MIT

mcp-name: io.github.VirajMishra1/wander-agent