# Travel Planner MCP Server
A multi-agent travel planning system built with [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) that exposes its tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
The system uses a **root agent** with two **sub-agents** — a weather agent and a travel plan agent — to create weather-aware 3-day travel itineraries. The tools are also exposed through an MCP server, making them accessible to any MCP-compliant client.
## Architecture
```
┌─────────────────────────────────────────────────┐
│ Root Agent │
│ (travel_planner) │
│ │
│ Orchestrates the travel planning workflow: │
│ gather info → check weather → create plan │
│ │
│ ┌─────────────────┐ ┌──────────────────────┐ │
│ │ Weather Agent │ │ Travel Plan Agent │ │
│ │ │ │ │ │
│ │ get_weather() │ │ create_travel_plan()│ │
│ │ (Open-Meteo API)│ │ (itinerary builder) │ │
│ └─────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────┘
▼ exposed via ▼
┌─────────────────────────────────────────────────┐
│ MCP Server (stdio) │
│ │
│ Wraps ADK FunctionTools and exposes them as │
│ MCP tools accessible to any MCP client │
│ │
│ Tools: get_weather, create_travel_plan │
└─────────────────────────────────────────────────┘
```
## Project Structure
```
travel-planner-mcp-server/
├── travel_planner/ # ADK multi-agent package
│ ├── __init__.py
│ ├── agent.py # Root agent (orchestrator with sub-agents)
│ ├── sub_agents/
│ │ ├── __init__.py
│ │ ├── weather_agent.py # Weather specialist sub-agent
│ │ └── travel_plan_agent.py # Travel planning specialist sub-agent
│ └── tools/
│ ├── __init__.py
│ ├── weather_tools.py # Open-Meteo API weather tool
│ └── travel_tools.py # Travel plan generation tool
├── mcp_server.py # MCP server exposing ADK tools
├── adk_client_agent/ # Example ADK agent consuming the MCP server
│ └── mcp_travel_client/
│ ├── __init__.py
│ └── agent.py
├── pyproject.toml
├── requirements.txt
├── .env.example
└── README.md
```
## Prerequisites
- Python 3.10+
- A Google API key (for Gemini model access)
## Setup
1. **Clone the repository:**
```bash
git clone <repo-url>
cd travel-planner-mcp-server
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Configure environment:**
```bash
cp .env.example .env
# Edit .env and add your Google API key
```
## Usage
### Option 1: Run the ADK Multi-Agent System Directly
This uses the root agent with its sub-agents through the ADK web UI:
```bash
adk web
# Select "travel_planner" in the browser UI
```
The root agent will:
1. Ask for your destination and travel date
2. Delegate to the **weather agent** to fetch the forecast
3. Delegate to the **travel plan agent** to create the itinerary
4. Present a comprehensive 3-day travel plan
### Option 2: Run the MCP Server
This exposes the tools via MCP protocol for any MCP client to consume:
```bash
python mcp_server.py
```
The MCP server exposes two tools:
- **`get_weather`** — Fetches 3-day weather forecast for a location using Open-Meteo API
- **`create_travel_plan`** — Generates a structured 3-day travel itinerary template
### Option 3: Run the MCP Client Agent
This demonstrates an ADK agent consuming the MCP server:
```bash
cd adk_client_agent
adk web
# Select "mcp_travel_client" in the browser UI
```
### Option 4: Connect from Any MCP Client
Add to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"travel-planner": {
"command": "python3",
"args": ["/path/to/mcp_server.py"]
}
}
}
```
## Tools
### `get_weather`
Fetches a 3-day weather forecast using the [Open-Meteo API](https://open-meteo.com/) (free, no API key required).
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `location` | string | City or place name (e.g., "Paris", "Tokyo") |
| `date` | string | Start date in YYYY-MM-DD format |
**Returns:** Temperature (C/F), conditions, precipitation, wind speed, and UV index for 3 days.
### `create_travel_plan`
Generates a structured 3-day travel itinerary template.
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `location` | string | Destination city or place |
| `start_date` | string | Trip start date (YYYY-MM-DD) |
| `weather_summary` | string | Weather conditions summary |
| `interests` | string | Travel interests (default: "general sightseeing") |
**Returns:** Day-by-day itinerary structure with time slots, meals, and tips.
## How It Works
This project demonstrates **Pattern 2** from the ADK documentation: [Building an MCP server with ADK tools](https://google.github.io/adk-docs/tools-custom/mcp-tools/#2-building-an-mcp-server-with-adk-tools-mcp-server-exposing-adk).
1. ADK `FunctionTool` wraps the Python tool functions
2. `adk_to_mcp_tool_type()` converts ADK tool schemas to MCP format
3. The MCP server advertises tools via `list_tools` and executes them via `call_tool`
4. Any MCP client can discover and invoke the tools through the standard protocol
## License
MIT
