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:

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

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:

Step 2: Pull the Docker Image (Optional)

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

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:

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:

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

Place Discovery

Itinerary Planning

Distance Calculations

Advanced Usage Techniques

Multi-Step Planning

Engage in conversational planning that builds on previous responses:

Comparative Analysis

Ask Claude to compare multiple options:

Contextual Refinement

Refine itineraries based on constraints:

Complex Usage Examples

Example 1: Weekend Getaway Optimization

Example 2: Dynamic Re-planning

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:

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:

Function: generate_itinerary

Generate a customized travel itinerary.

Parameters:

Returns: Day-by-day itinerary with activities, locations, and recommendations.

Example:

Function: calculate_travel_distance

Calculate distance and estimated travel time between cities.

Parameters:

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

Example:

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:

Issue: Permission denied (Linux)

Solution:

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: