Travel Planner MCP Server

# 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](https://www.docker.com/products/docker-desktop/) - **Claude Desktop** app installed - [Download Claude Desktop](https://claude.ai/download) ### 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:** ```bash # 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: ```bash 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:** ```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 ### 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:** ```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" } ``` ## 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:** ```bash docker pull bajpaih22/travel-planner-mcp:latest ``` **Issue:** Permission denied (Linux) **Solution:** ```bash 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: ```bash 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: ```bash # 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> ```