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.

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: Offer 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 │ ◄─MCP──►│  Travel Planner  │ ◄─HTTP─►│  External APIs  │
│   (Client)      │         │   MCP Server     │         │  (Weather, etc) │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                    │
                                    │ Docker Container
                                    ▼
                            ┌──────────────────┐
                            │  Python Runtime  │
                            │  - httpx         │
                            │  - mcp >= 1.0    │
                            └──────────────────┘

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 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.10+
• Protocol: Model Context Protocol (MCP) 1.0+
• HTTP Client: httpx 0.27.0+
• Containerization: Docker
• Build System: Hatchling

Project Structure

travel-planner-mcp/
├── src/
│   └── travel_planner/
│       ├── __init__.py
│       ├── __main__.py
│       └── server.py          # MCP server implementation with Weather API integration, Place search functionality, Itinerary generation, Itinerary generation
├── pyproject.toml             # Project configuration
├── Dockerfile                 # Container definition
└── 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.10 or higher
• Docker runtime environment

Data Flow

1. Input: Natural language query from 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 isolated Docker container
• No persistent storage of user data
• API calls made on-demand only
• No authentication credentials stored in config

Installation & Setup

Prerequisites

• Docker installed and running on your system
  • Download Docker Desktop
• Claude Desktop app installed
  • Download Claude Desktop

Step 1: Install Docker

If you don't have Docker installed:

macOS/Windows:

1. Download and install Docker Desktop from the link above
2. Start Docker Desktop
3. Verify installation by running in terminal: docker --version

Linux:

# Install Docker Engine (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install docker.io
sudo systemctl start docker
sudo systemctl enable docker

Step 2: Pull the Docker Image (Optional)

The image will be automatically pulled when first used, but you can pre-download it:

docker pull bajpaih22/travel-planner-mcp:latest

Step 3: Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

Location of config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "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

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

Step 5: Verify Installation

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!

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:

{
  "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:

{
  "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:

{
  "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:

{
  "origin": "Berlin",
  "destination": "Munich"
}

Troubleshooting

Server not appearing in Claude

Issue: MCP server doesn't show up in Claude Desktop

Solutions:

• Verify Docker is running: docker ps should work without errors
• Check the config file path is correct for your OS
• Validate JSON syntax in the config file (use a JSON validator)
• Ensure the config file has proper read permissions
• Check Claude Desktop logs for error messages
• Try restarting both Docker Desktop and Claude Desktop

Docker-related Issues

Issue: "Cannot connect to Docker daemon"

Solution:

• Ensure Docker Desktop is running
• On Linux, start Docker: sudo systemctl start docker

Issue: "Image not found" or pull errors

Solution:

docker pull bajpaih22/travel-planner-mcp:latest

Issue: Permission denied (Linux)

Solution:

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Functions Not Working

Issue: Server connects but functions fail

Solutions:

• Verify the Docker container can start independently:

  docker run -i --rm bajpaih22/travel-planner-mcp:latest
  

• Check Docker Desktop logs for container errors
• Ensure you have internet connectivity for API calls
• Try pulling the latest image: docker pull bajpaih22/travel-planner-mcp:latest

Configuration Issues

Issue: Config file not being read

Solutions:

• Verify exact file path for your OS (see Installation Step 3)
• Check file is named exactly claude_desktop_config.json
• Ensure no trailing commas in JSON
• Validate JSON structure with a linter

Testing the Docker Image Directly

You can test if the Docker image works independently:

# Test basic execution
docker run -i --rm bajpaih22/travel-planner-mcp:latest

# Check if image is present
docker images | grep travel-planner-mcp

# View container logs if running
docker logs <container_id>