# Route & Gas Station Chatbot with MCP, Google ADK, and Google Maps

A local AI travel chatbot that calculates driving distance between two locations and finds gas stations near a route.

This project is built to understand the complete **Model Context Protocol (MCP)** flow:

```text
User -> Google ADK Chatbot -> MCP Client -> MCP Server -> Google Maps APIs
```

## Features

- Calculate driving distance and estimated travel duration
- Find gas stations near sampled points on a driving route
- Use Google ADK as the AI chatbot framework
- Use FastMCP to expose Python functions as MCP tools
- Use Google Routes API for driving routes
- Use Google Places API (New) for gas-station searches
- Run locally using Streamable HTTP MCP transport

## Architecture

```text
+------------------+
| User / ADK Web   |
| http://localhost |
+--------+---------+
         |
         | Natural-language request
         v
+------------------+
| Google ADK Agent |
| MCP Client       |
+--------+---------+
         |
         | http://127.0.0.1:8002/mcp
         v
+-------------------------------+
| FastMCP Server                |
| route_mcp_server.py           |
+---------------+---------------+
                |
                +----------------------------+
                |                            |
                v                            v
+--------------------------+   +--------------------------+
| Google Routes API        |   | Google Places API (New)  |
| Distance and duration    |   | Gas stations             |
+--------------------------+   +--------------------------+
```

## Project Structure

```text
mcp-route-chatbot/
│
├── .env
├── .gitignore
├── README.md
├── requirements.txt
├── route_mcp_server.py
│
└── route_chatbot/
    ├── __init__.py
    └── agent.py
```

## Prerequisites

- Python 3.10 or later
- Google Gemini API key for Google ADK
- Google Maps Platform API key
- Google Cloud billing account connected to the Google Maps project
- Enabled Google Maps APIs:
  - Routes API
  - Places API (New)

## Setup

### 1. Clone the repository

```bash
git clone https://github.com/YOUR_GITHUB_USERNAME/mcp-route-chatbot.git
cd mcp-route-chatbot
```

### 2. Create and activate a virtual environment

**Windows PowerShell:**

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**macOS/Linux:**

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install dependencies

```bash
python -m pip install -r requirements.txt
```

### 4. Configure environment variables

Create a `.env` file in the project root:

```env
GOOGLE_API_KEY=your_gemini_api_key
GOOGLE_MAPS_API_KEY=your_google_maps_platform_api_key
```

> Never commit your `.env` file or API keys to GitHub.

## Google Maps Setup

1. Open [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new Google Cloud project
3. Link a billing account
4. Enable the following APIs:
   - Routes API
   - Places API (New)
5. Go to **APIs & Services -> Credentials**
6. Create an API key
7. Restrict the key to only:
   - Routes API
   - Places API (New)
8. Add the key to `.env` as `GOOGLE_MAPS_API_KEY`

## Run the Application

The project has two independently running services.

### Terminal 1: Start the MCP server

```bash
python route_mcp_server.py
```

Expected MCP endpoint:

```text
http://127.0.0.1:8002/mcp
```

### Terminal 2: Start ADK Web UI

```bash
adk web --port 8001
```

Open this URL in your browser:

```text
http://127.0.0.1:8001
```

Select the `route_chatbot` agent in the ADK Web UI.

## Example Prompts

Ask these questions in ADK Web UI:

```text
What is the driving distance from Phoenix, Arizona to Sedona, Arizona?
```

```text
How long does it take to drive from Phoenix, Arizona to Flagstaff, Arizona?
```

```text
Find 5 gas stations from Phoenix, Arizona to Flagstaff, Arizona.
```

```text
Show gas stations on the route from Los Angeles, California to Las Vegas, Nevada.
```

## MCP Tools

The FastMCP server exposes these tools to the ADK agent.

| Tool | Purpose |
|---|---|
| `route_distance` | Returns driving distance in miles/kilometers and estimated driving time |
| `gas_stations_on_route` | Finds gas stations around sampled coordinates along the route |

### `route_distance`

Example tool input:

```json
{
  "origin": "Phoenix, Arizona",
  "destination": "Sedona, Arizona"
}
```

Example response:

```json
{
  "origin": "Phoenix, Arizona",
  "destination": "Sedona, Arizona",
  "distance_km": 186.4,
  "distance_miles": 115.8,
  "estimated_drive_minutes": 125.0
}
```

### `gas_stations_on_route`

Example tool input:

```json
{
  "origin": "Phoenix, Arizona",
  "destination": "Flagstaff, Arizona",
  "max_results": 5
}
```

## Important Ports

| Service | Port | URL |
|---|---:|---|
| ADK Web UI | 8001 | `http://127.0.0.1:8001` |
| MCP Server | 8002 | `http://127.0.0.1:8002/mcp` |

Do not open the MCP URL directly in a browser. It is a Streamable HTTP endpoint for MCP clients and may return an error such as `Client must accept text/event-stream`. The ADK agent is the MCP client that should connect to this endpoint.

## API Cost Notes

Google Maps Platform APIs use pay-as-you-go pricing. This project can make:

- One Routes API call for a distance question
- One Routes API call plus several Places Nearby Search calls for a gas-station question

For learning and low-volume local usage, create a dedicated Google Cloud project and configure a small billing budget alert before testing.

## Troubleshooting

| Issue | Possible cause | Solution |
|---|---|---|
| `GOOGLE_MAPS_API_KEY is missing` | `.env` is missing or not loaded | Put `.env` beside `route_mcp_server.py`, then restart the server |
| `403 PERMISSION_DENIED` | API not enabled, billing not linked, or restricted key | Enable Routes API and Places API (New), verify billing and key restrictions |
| `404` on `http://127.0.0.1:8002/` | Normal behavior | Use the MCP endpoint `/mcp` only from the ADK client |
| `Client must accept text/event-stream` | MCP URL opened in a browser | This is expected; start ADK Web and let ADK connect |
| ADK cannot find MCP tools | Incorrect MCP URL or MCP server is stopped | Confirm `http://127.0.0.1:8002/mcp` and keep the MCP terminal running |
| `429 RESOURCE_EXHAUSTED` | API quota or rate limit | Reduce calls and review Google Cloud quotas and billing |

## Security

- Keep API keys only in `.env`
- Add `.env` to `.gitignore`
- Restrict the Google Maps API key to Routes API and Places API (New)
- Use IP restrictions when deploying the MCP server
- Do not expose server-side API keys in a frontend application

## Future Improvements

- Add real-time fuel price data from a fuel-price provider
- Add route preferences such as avoiding tolls or highways
- Recommend the best fuel stop based on rating, route position, and opening hours
- Add route map visualization
- Add unit tests with `pytest` and mocked Google API responses
- Dockerize the MCP server and ADK application
- Deploy the MCP server to Cloud Run or AWS ECS
- Add an approval step before sharing a travel plan

## Learning Outcomes

This project demonstrates:

- MCP server development with FastMCP
- MCP client integration with Google ADK
- Agent tool calling
- Streamable HTTP transport
- API-key management with `.env`
- Google Maps Routes API integration
- Google Places API integration
- Local multi-service application development

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.