# Travel Planner MCP Server
A Model Context Protocol (MCP) server that provides intelligent travel planning functionality through Claude. This server enables AI-assisted travel planning with real-time weather data, place discovery, itinerary generation, and route optimization.
## Contributions
* Harshita Bajpai: Project setup, Docker Hub and weather forcast Tool
* Luana Ferrero: Itinerary tool
* Ronja Bächle: Distances calculation tool
* André Deiss: Place Search tool
* Lukas Vowinkel: Architecture Overview and Documentation
## Project Goals
### Primary Objectives
1. **Simplify Travel Planning**: Provide an AI-powered assistant that handles the complexity of multi-destination travel planning
2. **Real-Time Information**: Integrate live weather data and location information to help travelers make informed decisions
3. **Personalization**: Generate customized itineraries based on individual interests, budget constraints, and travel preferences
4. **Seamless Integration**: Offers a natural conversational interface through Claude Desktop using the Model Context Protocol
### Use Cases
- **Trip Planning**: End-to-end itinerary creation for single or multi-city trips
- **Destination Research**: Quick discovery of attractions, restaurants, and points of interest
- **Weather Preparation**: Forecast checking to help with packing and activity planning
- **Route Optimization**: Distance and time calculations for efficient travel routing
- **Budget Management**: Tailored recommendations based on spending comfort levels
## System Architecture
### Overview
The Travel Planner MCP server follows a client-server architecture utilizing the Model Context Protocol:
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Desktop Client │
│ (User Interface Layer) │
└────────────────────────┬────────────────────────────────────┘
│ MCP Protocol (SSE)
│
┌────────────────────────▼───────────────────────────────────┐
│ MCP Server (FastMCP) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Travel Planner Agent Core │ │
│ │ • Request Router │ │
│ │ • Context Manager │ │
│ │ • Response Formatter │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────┬──────────────┬─────────────┬──────────┐ │
│ │ Tool 1: │ Tool 2: │ Tool 3: │ Tool 4: │ │
│ │ Weather │ Places │ Itinerary │ Distance │ │
│ │ Forecast │ Search │ Generator │ Matrix │ │
│ └──────┬───────┴──────┬───────┴──────┬──────┴────┬─────┘ │
└─────────┼──────────────┼──────────────┼───────────┼────────┘
│ │ │ │
┌─────────▼──────┐ ┌─────▼─────────┐ ┌──▼───────┐ ┌─▼─────────┐
│ Weather API │ │ Places API │ │ LLM │ │ Geo API │
│ (Open-Meteo) │ │(OpenStreetMap)│ │(Claude) │ │(Nominatim)│
└────────────────┘ └───────────────┘ └──────────┘ └───────────┘
```
### Components
1. **MCP Server** (`travel_planner`)
- Implements MCP protocol for tool exposure
- Handles requests from Claude Desktop
- Manages API communications
2. **Docker Container**
- Encapsulates the entire runtime environment
- Ensures consistent execution across platforms
- Simplifies deployment and dependency management
3. **External Services**
- Weather API integration for forecast data
- Geographic databases for place information
- Distance calculation services
### Communication Flow
1. User sends natural language query to Claude Desktop
2. Claude identifies relevant travel planning tools via MCP
3. MCP server receives structured function calls
4. Server processes requests, calls external APIs if needed
5. Results are returned to Claude for natural language presentation
6. User receives a formatted, conversational response
## Features & Capabilities
### 1. Weather Forecasting
Get accurate weather predictions for any destination to plan activities and packing.
**Capabilities:**
- Multi-day forecasts (1-7 days)
- Temperature, conditions, and precipitation data
- Supports cities worldwide
### 2. Place Discovery
Search for points of interest across multiple categories.
**Capabilities:**
- Tourism attractions and landmarks
- Restaurant recommendations
- Museums and cultural sites
- Parks and outdoor spaces
- Customizable result limits
### 3. Itinerary Generation
AI-powered creation of day-by-day travel plans.
**Capabilities:**
- Interest-based activity selection
- Budget-aware recommendations (low/moderate/high)
- Multi-day trip planning
- Balanced daily schedules
### 4. Travel Distance Calculation
Compute distances and estimated travel times between cities.
**Capabilities:**
- Inter-city distance calculation
- Time estimates for journey planning
- Route feasibility assessment
## Technical Details
### Technology Stack
- **Language**: Python 3.12+
- **Protocol**: Model Context Protocol (MCP) 1.0+
- **HTTP Client**: httpx
- **Containerization**: Docker
- **Dependency Management**: Direct pip installation in container
### Project Structure
```
travel-planner-mcp/
├── src/
│ └── travel_planner/
│ ├── __init__.py
│ └── server.py # MCP server implementation with Weather API integration, Place search functionality, Itinerary generation, Itinerary generation
├── pyproject.toml # Project configuration
├── Dockerfile # Container definition
├── claude_desktop_config.json # Claude Desktop configuration
├── uv.lock # Dependency lock file
└── README.md # This file
```
### Dependencies
**Core Dependencies:**
- `mcp>=1.0.0` - Model Context Protocol implementation
- `httpx>=0.27.0` - Async HTTP client for external API calls
**Runtime:**
- Python 3.12 or higher
- Docker runtime environment
### Data Flow
1. **Input**: Natural language query from a user
2. **Processing**: Claude interprets intent and selects appropriate tools
3. **Execution**: MCP server executes tool with parameters
4. **Data Retrieval**: External APIs provide requested data
5. **Response**: Structured data returned to Claude
6. **Output**: Natural language response to user
### Security & Privacy
- Server runs in an isolated Docker container
- No persistent storage of user data
- API calls are made on-demand only
- No authentication credentials stored in config
## Installation
### Install Docker Desktop (Optional if installed)
**macOS/Windows:**
1. Download and install Docker Desktop from [Download Docker Desktop](https://www.docker.com/products/docker-desktop/)
2. Start Docker Desktop
3. Verify installation by running in terminal: `docker --version`
### Install Claude Desktop (Optional if installed)
[Download Claude Desktop](https://claude.ai/download) and follow instructions
## Setup
### Step 1: Run Docker Desktop
Start Docker Hub
### Step 2: Configure Claude Desktop
Add the MCP server to your Claude Desktop configuration file:
1. Open Claude Desktop
2. Open settings
3. Navigate to Desktop app: Developer
4. "Edit Config"
5. The config file will be shown
6. Open the file with a text editor and override the content with this configuration:
```json
{
"mcpServers": {
"travel-planner": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"bajpaih22/travel-planner-mcp:latest"
]
}
}
}
```
**Configuration explanation:**
- `command: "docker"` - Uses Docker to run the server
- `run -i` - Runs container in interactive mode
- `--rm` - Automatically removes container when it exits
- `bajpaih22/travel-planner-mcp:latest` - Docker Hub image
7. Save and close the file
### Step 3: Restart Claude Desktop
Close and reopen Claude Desktop to load the new MCP server.
### Step 4: Verify Installation
**Option 1:**
In Claude Desktop, try a simple query like:
```
What's the weather in London for the next 3 days?
```
If Claude responds with weather information using the travel-planner tools, the setup is successful!
**Option 2**:
Open a new chat and click on the "Search and tools" menu. Here you should see the "travel-planner" tool.
**Option 3**:
Go in the settings to the Claude Developer Desktop tab. Here a blue "running" should be there
## Usage Guide
### Basic Usage Patterns
The Travel Planner MCP works through natural conversation with Claude. Here are common usage patterns:
#### Weather Queries
```
"What's the weather forecast for Tokyo next week?"
"Will it rain in Paris this weekend?"
"Show me the 5-day forecast for New York"
```
#### Place Discovery
```
"Find the best restaurants in Rome"
"What are the top museums in London?"
"Show me parks in San Francisco"
"List 10 tourist attractions in Barcelona"
```
#### Itinerary Planning
```
"Create a 3-day itinerary for Amsterdam focusing on art and history"
"Plan a week-long trip to Thailand with beaches and temples, moderate budget"
"Generate a family-friendly 5-day Paris itinerary with a low budget"
```
#### Distance Calculations
```
"How far is it from Berlin to Prague?"
"What's the travel time between Los Angeles and San Diego?"
"Calculate the distance from Madrid to Barcelona"
```
### Advanced Usage Techniques
#### Multi-Step Planning
Engage in conversational planning that builds on previous responses:
```
User: "I'm planning a trip to Italy"
Claude: [Asks clarifying questions]
User: "Show me weather for Rome, Florence, and Venice in May"
Claude: [Provides weather forecasts]
User: "Find museums in each city"
Claude: [Lists museums]
User: "Create a 7-day itinerary visiting all three cities, moderate budget"
Claude: [Generates comprehensive itinerary]
```
#### Comparative Analysis
Ask Claude to compare multiple options:
```
"Compare weather between Bali and Phuket for next month and recommend which is better for a beach vacation"
```
#### Contextual Refinement
Refine itineraries based on constraints:
```
User: "Generate a 4-day Tokyo itinerary for food lovers"
Claude: [Creates itinerary]
User: "Adjust this to focus more on ramen shops and street food"
Claude: [Refines itinerary]
User: "What if I only have a low budget?"
Claude: [Adjusts recommendations]
```
## Complex Usage Examples
### Example 1: Weekend Getaway Optimization
```
User: I have a free weekend and I'm in San Francisco. I want to visit somewhere
within 300 miles that has good weather, outdoor activities, and isn't too expensive.
Can you suggest options?
Claude will:
1. Calculate distances to potential destinations (LA, San Diego, Lake Tahoe, Yosemite)
2. Check weather forecasts for each location
3. Search for parks and outdoor attractions in promising destinations
4. Generate 2-3 day itineraries for the best options with low/moderate budget
5. Compare options to help you decide based on weather, activities, and travel time
Result: Personalized comparison of 2-3 destinations with pros/cons for each
```
### Example 2: Dynamic Re-planning
```
User: I have a 5-day trip to Japan planned. Create an itinerary for Tokyo
focusing on technology and anime culture.
[Claude creates initial itinerary]
User: What's the weather forecast?
[Claude checks weather, finds rain expected]
User: Adjust the itinerary to include more indoor activities during the rainy days
[Claude reorganizes activities based on weather]
User: How far is Kyoto from Tokyo? Can I do a day trip?
[Claude calculates distance and suggests modification]
```
## API Reference
### Function: `get_weather_forecast`
Retrieve weather forecasts for a destination city.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `city` | string | Yes | - | Name of the destination city |
| `days` | integer | No | 3 | Number of days to forecast (1-7) |
**Returns:**
Weather data including temperature, conditions, precipitation, and other relevant metrics.
**Example:**
```json
{
"city": "Paris",
"days": 5
}
```
---
### Function: `search_places`
Search for places of interest in a city by category.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `city` | string | Yes | - | Name of the city to search |
| `place_type` | string | No | "tourism" | Type of place (tourism, restaurant, museum, park) |
| `limit` | integer | No | 5 | Maximum number of results |
**Returns:**
List of places with names, descriptions, and relevant details.
**Example:**
```json
{
"city": "Tokyo",
"place_type": "restaurant",
"limit": 10
}
```
---
### Function: `generate_itinerary`
Generate a customized travel itinerary.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `destination` | string | Yes | - | Destination city or country |
| `duration_days` | integer | Yes | - | Number of days for the trip |
| `interests` | string | Yes | - | Comma-separated interests (e.g., "history, food, nature") |
| `budget` | string | No | "moderate" | Budget level: "low", "moderate", or "high" |
**Returns:**
Day-by-day itinerary with activities, locations, and recommendations.
**Example:**
```json
{
"destination": "Rome",
"duration_days": 5,
"interests": "history, food, architecture",
"budget": "moderate"
}
```
---
### Function: `calculate_travel_distance`
Calculate distance and estimated travel time between cities.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `origin` | string | Yes | - | Starting city |
| `destination` | string | Yes | - | Destination city |
**Returns:**
Distance in kilometers/miles and estimated travel time.
**Example:**
```json
{
"origin": "Berlin",
"destination": "Munich"
}
```
