MCP server · MIT
Give Claude a real travel stack.
TripMate ships a Model Context Protocol server that exposes five travel tools over stdio: geocoding, nearby place search, weather, driving routes, and itinerary planning. Four of the five tools need no API key.
- Runtime
- Node 20+
- Transport
- stdio
- Tools
- 5
- License
- MIT
What it does
The tools your agent was missing.
Most chat models guess at coordinates, opening hours, and drive times. TripMate’s MCP server replaces those guesses with named API calls, so the itinerary is grounded in places that exist and a forecast that is current.
Runs locally
A single Node process that speaks stdio. There is no TripMate account, no hosted endpoint, and no extra service to deploy.
Returns structured data
Tool responses are JSON. plan_trip parses Gemini's reply and returns days, activities, and estimated costs as data rather than prose.
Grounded in live sources
OpenStreetMap for places, Open-Meteo for forecasts, OSRM for routes, and Gemini for planning. Every source is named in the output.
Tools
Five tools, one server.
Each tool has a typed input schema and returns JSON. The first four are key-free; plan_trip adds AI planning on top of the same live data.
| Tool | Input | What it returns | Key |
|---|---|---|---|
geocode_place | query, limit | Latitude, longitude, address, place type, and country code from OpenStreetMap Nominatim. | None |
search_places | latitude, longitude, category, radius_km, limit | Named attractions, restaurants, cafes, hotels, or bars with coordinates, addresses, websites, and opening hours when tagged. | None |
get_weather | latitude, longitude, days, start_date, end_date | Daily min/max temperature, condition, and rain chance from Open-Meteo, up to 16 days ahead. | None |
get_directions | from, to | Driving distance and duration between two named places from the public OSRM server. | None |
plan_trip | destination, start_date, end_date, budget_level, travel_style, preferences, travelers, model | A structured day-by-day itinerary built from live weather and nearby places, with estimated costs and packing tips. | GEMINI_API_KEY |
All tools are read-only. search_places accepts attractions, food, cafes, hotels, or nightlife, with a radius of 0.5–15 km.
Install
Clone, install, verify.
The server lives in the mcp/ directory next to the web app. You need Node.js 20 or newer and npm; nothing else is required for the four key-free tools.
git clone https://github.com/Krithik-m-codes/tripmate.git
cd tripmate/mcp
npm install
# Syntax check, then a live smoke test against the public APIs
npm run check
npm run smokeThe smoke test starts the server, lists its tools, and calls the public data sources once. If it passes, the server is ready to wire into a client.
Connect
Works with the client you already use.
Any MCP client with stdio support can load the server. Use an absolute path to server.mjs and restart the client after changing its config.
Claude Desktop
Add the entry to claude_desktop_config.json. On macOS it lives at ~/Library/Application Support/Claude/; on Windows at %APPDATA%\Claude\. Use forward slashes in the path on Windows.
{
"mcpServers": {
"tripmate": {
"command": "node",
"args": ["/absolute/path/to/tripmate/mcp/server.mjs"],
"env": {
"GEMINI_API_KEY": "your-key-here"
}
}
}
}Cursor
Create .cursor/mcp.json in your project, or add the same block to Cursor’s global MCP settings. The config shape is identical.
{
"mcpServers": {
"tripmate": {
"command": "node",
"args": ["/absolute/path/to/tripmate/mcp/server.mjs"],
"env": {
"GEMINI_API_KEY": "your-key-here"
}
}
}
}Claude Code
Register the server from your shell. Claude Code inherits the environment it starts with, so export GEMINI_API_KEY before launching it if you want plan_trip.
claude mcp add tripmate -- node /absolute/path/to/tripmate/mcp/server.mjs
# POSIX shells
GEMINI_API_KEY=your-key-here claude
# PowerShell
$env:GEMINI_API_KEY="your-key-here"; claudeTry it
Ask in plain language.
Once connected, describe the trip you want. The agent decides which tools to call, then hands back an itinerary you can edit.
Full itinerary
“Plan a 5-day trip to Lisbon in mid-November for two people. Mid-range budget, food-first, one day trip outside the city.”
Direct tool call
“Find four viewpoints near 38.7223, -9.1393 within 3 km.”
Route plus weather
“What is the driving time from Lisbon to Sintra? Check the forecast for the day I go.”
Configuration
Three variables, one optional key.
The server reads variables from the process environment, not from a .env file. Your MCP client must pass them through its env block.
| Variable | Required | Purpose |
|---|---|---|
GEMINI_API_KEY | For plan_trip | Google AI Studio key. The other four tools work without it. |
GEMINI_MODEL | No | Override the Gemini model. Defaults to gemini-1.5-flash. |
TRIPMATE_USER_AGENT | No | Contact string sent to Nominatim. Set this if you run your own instance or send steady traffic. |
Need the full web app too? See the self-hosting guide for database, auth, and email variables.
Limits
Free public data has boundaries.
TripMate uses public, key-free services by default. They are fine for individual planning and demos, but they are not a bulk data feed.
- Nominatim
- The public OpenStreetMap instance allows about one request per second. The server serialises calls, so large batches are slow by design. Set TRIPMATE_USER_AGENT for steady use.
- Open-Meteo
- Forecasts cover up to 16 days ahead. Dates beyond that window return a note instead of invented weather.
- OSRM
- get_directions uses the public OSRM demo server and returns driving routes only. Check OSRM's usage policy before production traffic.
- plan_trip
- Trips longer than 21 days are rejected. Costs are AI planning estimates, not live flight or hotel prices. Confirm opening hours and availability with the venue.
Troubleshooting
Four fixes that solve most setup issues.
Most connection problems come from a relative path, a stale client process, or a missing key. Check these first.
| Symptom | Fix |
|---|---|
| The client shows no tools | Use an absolute path to server.mjs, save the config, and fully restart the client. |
| plan_trip reports a missing GEMINI_API_KEY | Add the key to the client's env block, or export it before starting Claude Code. |
| Geocoding returns nothing | Use a more specific query, such as “Lisbon, Portugal” instead of “Lisbon”. |
| Weather is missing for your dates | The trip is outside the 16-day forecast window. Plan with seasonal norms instead. |
FAQ
MCP server questions.
Short answers to the questions that come up before installing.
What is the TripMate MCP server?
+
TripMate's MCP server is a local Model Context Protocol process that gives an AI client five travel tools: geocode_place, search_places, get_weather, get_directions, and plan_trip. It runs over stdio and needs no hosting.
Do I need an API key to use the MCP server?
+
No for four of the five tools. Geocoding, nearby place search, weather, and driving routes call free public services. Only plan_trip needs a Google Gemini API key.
Which MCP clients work with TripMate?
+
Any MCP client that supports stdio transport, including Claude Desktop, Cursor, and Claude Code. The setup guide includes a ready-to-paste configuration block for each.
Does the MCP server work offline?
+
No. Every tool calls a live public API: OpenStreetMap Nominatim, Open-Meteo, OSRM, or Google Gemini. The server itself is local, but the data is fetched at call time.
Can the MCP server change or book anything?
+
No. All five tools are read-only. The server cannot book flights, hotels, or activities, and the costs it returns are planning estimates rather than live quotes.
Next step
Wire it into your client in five minutes.
Clone the repository, run the smoke test, and paste one config block. The server is MIT licensed and read-only by design.