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 di