# 🌍 Travel Planner MCP Server

An intelligent agentic system for travel planning built with Model Context Protocol (MCP).

##  Quick Start



### Prerequisites
- Docker installed
- Claude Desktop app

### Installation

1. **Pull Docker Image**
```bash
docker pull YOUR_DOCKERHUB_USERNAME/travel-planner-mcp:latest
```

2. **Configure Claude Desktop**

Edit your Claude Desktop config file:
- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this configuration:
```json
{
  "mcpServers": {
    "travel-planner": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "YOUR_DOCKERHUB_USERNAME/travel-planner-mcp:latest"
      ]
    }
  }
}
```

3. **Restart Claude Desktop**

## 🔧 Development Setup
```bash
# Create virtual environment
/opt/homebrew/bin/python3.12 -m venv .venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx anthropic

# Run server
python src/travel_planner/server.py
```

## 📚 Usage Examples

- "What's the weather like in Paris for the next 5 days?"
- "Find tourist attractions in Rome"
- "Create a 4-day itinerary for Tokyo focusing on traditional culture"
- "How far is it from London to Edinburgh?"

## API Keys

### Free APIs Used (No Keys Required!)
- **Open-Meteo API**: Weather forecasting
- **OpenStreetMap/Nominatim**: Geocoding and location data
- **Overpass API**: Points of interest search

All tools work without any API keys!

## 🛠️ Technical Details

### Technologies
- **Language**: Python 3.12+
- **Framework**: FastMCP (Model Context Protocol)
- **Containerization**: Docker
- **APIs**: httpx for async HTTP requests
- **External Services**: All free, no authentication required

### Tools Specification

1. **get_weather_forecast**: Real-time weather data from Open-Meteo
2. **search_places**: Find attractions using OpenStreetMap/Overpass
3. **generate_itinerary**: Template-based itinerary generator (no AI key needed)
4. **calculate_travel_distance**: Haversine distance calculations