BajpaiH22/DT1_assigment_2_MCP_Server_Claude

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
2. Start Docker Desktop
3. Verify installation by running in terminal: docker --version

Install Claude Desktop (Optional if installed)

Download Claude Desktop 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:

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

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:

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:

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:

Returns: Distance in kilometers/miles and estimated travel time.

Example:

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