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

Related MCP server: MCP Travel Concierge Server

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?

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:

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

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

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.