trip-search-mcp

Let Claude plan trips for you, in plain English. Live searches against Google Flights, Google Hotels, vacation rentals, Airbnb, Tripadvisor activities, and event ticket vendors — plus weather forecasts, currency conversion, persistent price watches, and per-property detail drill-downs. Eleven tools, one config block.

You:   Find me round-trip flights Helsinki → Washington DC for May 18,
       returning May 29, one stop or fewer.

Claude: [calls search_flights with WAS auto-expanded to IAD, DCA, BWI;
        merges 3 parallel results, ranks cheapest first, returns a
        summary with "Book on Google Flights" links]

📋 FEATURES.md has the full plain-English feature list with paste-ready example prompts for every capability — read that to see what's possible.

📐 TRIP-PLANNING-EXPANSION-SPEC.md tracks the five-track expansion plan (weather, currency, events, activities, drill-down). Weather is shipped; the other four are queued.

---

Before you start

You need:

• A computer running macOS, Windows, or Linux
• Claude Desktop, signed in
• About 5 minutes the first time

You do NOT need an account anywhere except Claude — unless you also want hotel search, which uses a free SerpAPI key (covered as an optional step below).

---

Install — step by step

Everything below happens in your Terminal app (macOS/Linux) or PowerShell (Windows).

Don't know what a terminal is? macOS: press ⌘+Space, type Terminal, press Enter. Windows: press the Win key, type PowerShell, press Enter.

1. Install Python 3.12 (skip if you already have it)

python3 --version

If you see Python 3.12.x or higher, jump to step 2. Otherwise install uv — one line, brings Python with it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a fresh terminal window after the installer finishes so the uv command is on your path.

2. Download the project

git clone https://github.com/nanwer/trip-search-mcp.git
cd trip-search-mcp

Missing git? macOS: run xcode-select --install. Windows: install from git-scm.com and reopen PowerShell.

3. Install the package

uv venv
uv pip install -e .

Creates .venv/ and installs everything. About 30 seconds.

4. Find the absolute path to the venv Python

You'll paste this into Claude Desktop's config in the next step.

# macOS / Linux
echo "$(pwd)/.venv/bin/python"

# Windows
echo "$(Resolve-Path .\.venv\Scripts\python.exe)"

Copy what it prints — looks like /Users/you/trip-search-mcp/.venv/bin/python (macOS) or C:\Users\you\trip-search-mcp\.venv\Scripts\python.exe (Windows).

5. Add a trip-search entry to Claude Desktop's config

This is the one step where you have to edit a text file by hand (or get Claude to edit it for you — see the callout below). The file is JSON; if you've never edited JSON before, just be careful with commas and quotes.

Where is the file?

OS	Path	Quickest way to find it
macOS	~/Library/Application Support/Claude/claude_desktop_config.json	In Finder, hit ⌘+Shift+G and paste ~/Library/Application Support/Claude/. Or run the open -e command below.
Windows	%APPDATA%\Claude\claude_desktop_config.json	In File Explorer, paste %APPDATA%\Claude\ into the address bar. Or run the notepad command below.
Linux	~/.config/Claude/claude_desktop_config.json	Open in your favorite text editor.

Open the config file:

# macOS
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Windows
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

5a. Pick your scenario

The config file is shared across every MCP server Claude Desktop knows about. Read the right scenario below before editing — adding trip-search to a file that already has other servers in it is different from setting it up from scratch.

🛟 Not sure which scenario you're in or worried about breaking things? Take a screenshot of your current config file (or copy-paste its contents) into a Claude chat and ask: "Merge a trip-search block into this MCP config without removing my existing servers. My venv Python path is /PASTE/PATH/FROM/STEP-4/HERE." Claude will hand back the full merged JSON. Paste that back into the file. No JSON wrangling required.

---

Scenario A — You've never set up an MCP server before (fresh file)

The file probably doesn't exist yet. Create it:

# macOS
mkdir -p "$HOME/Library/Application Support/Claude"
cat > "$HOME/Library/Application Support/Claude/claude_desktop_config.json" << 'JSON'
{
  "mcpServers": {
    "trip-search": {
      "command": "/PASTE/PATH/FROM/STEP-4/HERE",
      "args": ["-m", "trip_search_mcp.server"]
    }
  }
}
JSON

# Windows
New-Item -ItemType Directory -Path "$env:APPDATA\Claude" -Force | Out-Null
@'
{
  "mcpServers": {
    "trip-search": {
      "command": "C:\\PASTE\\PATH\\FROM\\STEP-4\\python.exe",
      "args": ["-m", "trip_search_mcp.server"]
    }
  }
}
'@ | Out-File -Encoding utf8 "$env:APPDATA\Claude\claude_desktop_config.json"

Then open it in a text editor and replace /PASTE/PATH/FROM/STEP-4/HERE with the path you copied in step 4. Windows users: every \ in the path must be doubled to \\.

---

Scenario B — You already have other MCP servers configured

Your file looks something like this (the names will differ — yours might have Outline, Slack, Figma, etc.):

{
  "mcpServers": {
    "outline": {
      "command": "...",
      "args": [...],
      "env": {...}
    }
  }
}

You need to add the trip-search block alongside your existing one(s). Open the file:

# macOS
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Windows
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Then add "trip-search": { ... } inside mcpServers. The result should look like this:

{
  "mcpServers": {
    "outline": {
      "command": "...",
      "args": [...],
      "env": {...}
    },
    "trip-search": {
      "command": "/PASTE/PATH/FROM/STEP-4/HERE",
      "args": ["-m", "trip_search_mcp.server"]
    }
  }
}

⚠️ Two things to watch out for:

1. Don't forget the comma after the closing } of your existing server block, before "trip-search":. Without it, the file is invalid JSON and Claude Desktop will load no MCP servers.
2. Windows paths: every \ in the command field must be doubled (\\). Example:

   "command": "C:\\Users\\you\\trip-search-mcp\\.venv\\Scripts\\python.exe"
   

Save the file when done.

Lost the formatting? Paste your file's current contents (and the path from step 4) into a Claude chat and ask it to add the trip-search block for you. Way safer than hand-editing if you're not comfortable with JSON.

6. Fully quit and reopen Claude Desktop

Closing the window isn't enough. Quit from the menu bar (macOS: ⌘Q or right-click the dock icon → Quit) or from the system tray (Windows: right-click the Claude icon → Quit). Then reopen.

7. Test it

Open a new chat in Claude Desktop. Click the hammer/tools icon at the bottom of the message box — you should see trip-search with 7 always-on tools plus 4 more after step 8 below:

Tool	Needs SERPAPI_KEY?
search_flights	No
search_cheapest_dates	No
search_stays with category="airbnb"	No
get_weather_forecast	No
convert_currency	No
watch_flight_price / list_active_watches / cancel_watch	No
search_stays (default / hotels / vacation_rentals)	Yes
get_stay_details	Yes
search_events	Yes
search_activities	Yes

Ask Claude:

"Find me round-trip flights from JFK to LHR, leaving July 12 returning July 22, 1 adult, economy."

If you get a summary with prices and a "Book on Google Flights" link, you're done. Browse FEATURES.md for everything else you can ask.

---

Step 8 (optional) — turn on hotel + event + activity search

Hotels, vacation rentals, events, activities, and get_stay_details use SerpAPI — free tier 100 searches/month. The flight tools, the Airbnb category, weather, currency, and watches all work without it.

1. Sign up at serpapi.com (Google login works).

2. Copy your key from serpapi.com/manage-api-key.

3. Open your config file again and add an env block to the trip-search entry. Two scenarios:

   If trip-search is your only MCP server, your file becomes:

   {
     "mcpServers": {
       "trip-search": {
         "command": "/PASTE/PATH/FROM/STEP-4/HERE",
         "args": ["-m", "trip_search_mcp.server"],
         "env": {
           "SERPAPI_KEY": "paste-your-key-here"
         }
       }
     }
   }
   

   If you have other MCP servers alongside trip-search, only modify the trip-search block — leave the others untouched:

   {
     "mcpServers": {
       "outline": { ... },        // leave alone
       "slack":   { ... },        // leave alone
       "trip-search": {
         "command": "/PASTE/PATH/FROM/STEP-4/HERE",
         "args": ["-m", "trip_search_mcp.server"],
         "env": {                    // ← add this block
           "SERPAPI_KEY": "paste-your-key-here"
         }
       }
     }
   }
   

   ⚠️ Don't forget the comma after "args": [...] before "env": — without it, the JSON is invalid.

4. ⌘Q and reopen Claude Desktop. The four SerpAPI-gated tools (search_stays hotels mode, get_stay_details, search_events, search_activities) now work.

🛟 Again, if you'd rather not hand-edit JSON, paste your current config plus the API key into a Claude chat and ask it to add the SerpAPI env block for you. Faster than chasing missing commas.

---

If something doesn't work

Symptom	Fix
The trip-search server doesn't appear in Claude's tools menu	You forgot to fully quit. ⌘Q (or quit from the system tray on Windows), then reopen.
search_stays says "SERPAPI_KEY is not set"	The env block is missing or you reopened Claude before saving the config. Re-check step 8, then ⌘Q + reopen.
Claude says "the tool call timed out"	A previous Claude Desktop quit may have left a stale MCP subprocess running. Run pgrep -f trip_search_mcp — if more than 2 PIDs show up, run pkill -f trip_search_mcp.server (macOS/Linux) or End Task on every Claude process in Task Manager (Windows), then ⌘Q + reopen.
ModuleNotFoundError: No module named 'trip_search_mcp'	The command path in your config points to the wrong Python. Re-run step 4 and paste that exact path.
Airbnb search returns an upstream_error	Airbnb sometimes pushes back on scraping during high traffic. Wait a few minutes and retry. If it keeps failing, pyairbnb may need a release.

docs/SETUP.md has a longer, verbose walkthrough.

---

Card / button rendering — baked into the server

The MCP server publishes server-level instructions at handshake time that tell Claude:

1. Render multi-result tool output as an HTML artifact with one card per result (not as prose).
2. Every booking partner gets its own button, side-by-side.

These instructions load once when Claude Desktop connects to the server and persist for the whole chat — you don't have to remember to add anything to your prompts.

If you still see prose-with-markdown-links for a specific query (Claude has discretion), you can reinforce with:

"Render every multi-result tool output as an HTML/React artifact card with prominent buttons — don't summarize as prose."

Or for a single combined trip-plan artifact:

"Put the final trip plan in a single HTML artifact. Each item is a card with a big rounded 'Book on X' button — not a markdown link."

The directive lives in src/trip_search_mcp/server.py as _SERVER_INSTRUCTIONS. Edit it there if you want to tune the behavior for your own use.

---

Updating to the latest version

Claude Desktop spawns the MCP subprocess once at launch and keeps running it. Pulling new code doesn't reload the running process — you have to ⌘Q and reopen Claude Desktop after every update.

Recent install (within the last few weeks)

cd /path/to/trip-search-mcp
git pull
uv pip install -e .          # reinstalls in case dependencies changed

Then ⌘Q Claude Desktop and reopen.

Verify:

.venv/bin/python -c "from trip_search_mcp.server import mcp; print(mcp.name)"
# → trip-search-mcp

Updating from an older version (before the flights-mcp → trip-search-mcp rename)

Older installs used the module name flights_mcp (now trip_search_mcp). If your Claude Desktop config still says -m flights_mcp.server, the server will fail to start with ModuleNotFoundError after the update. Three things to fix:

1. Pull and reinstall:

   cd /path/to/trip-search-mcp     # path is unchanged; GitHub redirects the old repo URL
   git pull
   uv pip install -e .              # picks up new deps including pyairbnb
   

2. Edit your Claude Desktop config. Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and update the args array:

   - "args": ["-m", "flights_mcp.server"]
   + "args": ["-m", "trip_search_mcp.server"]
   

   Optionally rename the JSON key from "flights" to "trip-search" so the entry in Claude Desktop's tools menu matches the new docs.

3. ⌘Q Claude Desktop and reopen.

Common gotchas during an update

Symptom	Cause / Fix
ModuleNotFoundError: No module named 'trip_search_mcp'	Your config still points at the old module name. See "Updating from an older version" above.
ModuleNotFoundError: No module named 'pyairbnb'	New dependency added since your install. Run uv pip install -e . to pick it up.
trip-search server shows "running" but new tools (search_stays, get_stay_details, watch_flight_price, …) don't appear	You didn't fully quit. Closing the window doesn't kill the subprocess on macOS or Windows. Use ⌘Q (macOS) or the system-tray Quit (Windows).
Updates seem to apply but a specific tool times out	Two MCP subprocesses may be running (Claude Desktop occasionally fails to kill the old one). Check with pgrep -f trip_search_mcp.server — if you see more than 2 PIDs, run pkill -f trip_search_mcp.server and reopen Claude Desktop.
The Claude Code CLI (not Desktop) doesn't see the updates	claude mcp commands cache server metadata. Restart your Claude Code session, or remove and re-add the server: claude mcp remove trip-search && claude mcp add trip-search -- /ABSOLUTE/PATH/TO/.venv/bin/python -m trip_search_mcp.server

---

For developers

.venv/bin/pytest -q          # 350 tests, all fixture-driven, no live API calls

Source layout:

src/trip_search_mcp/
├── server.py                FastMCP entry point — registers 7 tools
├── models.py                Pydantic I/O models
├── cache.py                 TTL response cache (tool-namespaced keys)
├── cities.py                City code → airport list map (27 cities)
├── errors.py                ErrorCode enum, ToolError, envelope helpers
├── logging_config.py        JSON-line file logger
├── tools/
│   ├── search_flights.py
│   ├── search_cheapest_dates.py
│   ├── search_stays.py
│   ├── get_stay_details.py
│   ├── watch_flight_price.py
│   ├── list_active_watches.py
│   └── cancel_watch.py
├── fli_backend/             flights — via fli library, no auth
├── serpapi_hotels_backend/  hotels + vacation rentals — SerpAPI
├── serpapi_events_backend/  concerts + festivals + sports — SerpAPI google_events
├── tripadvisor_backend/     things-to-do — SerpAPI Tripadvisor (ssrc=A)
├── airbnb_backend/          Airbnb direct — pyairbnb + Nominatim geocoding
├── open_meteo_backend/      weather forecasts — Open-Meteo, no auth
├── ecb_backend/             currency conversion — ECB daily feed, no auth
└── monitoring/              SQLite-backed price watches (lazy refresh)

Capture fresh real-data fixtures (uses live APIs — burns 1 call each):

.venv/bin/python scripts/verify_fli.py                  # flights
.venv/bin/python scripts/verify_serpapi_hotels.py       # hotels
.venv/bin/python scripts/verify_vacation_rentals.py     # rentals
.venv/bin/python scripts/verify_property_details.py     # property details

Further docs:

• FEATURES.md — every capability, plain English, with example prompts and combined-workflow scenarios.
• docs/SETUP.md — verbose install + troubleshooting.
• AGENTS.md — notes for AI coding agents working on this repo (topology, gotchas, hallucination traps).
• BACKLOG.md — completed items + new follow-ups surfaced during the work.

---

License

MIT.