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:

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

Related MCP server: MCP Google Maps

Architecture

+------------------+
| 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

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

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:

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

macOS/Linux:

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

3. Install dependencies

python -m pip install -r requirements.txt

4. Configure environment variables

Create a .env file in the project root:

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

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

python route_mcp_server.py

Expected MCP endpoint:

http://127.0.0.1:8002/mcp

Terminal 2: Start ADK Web UI

adk web --port 8001

Open this URL in your browser:

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:

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

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

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

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.

route_distance

Example tool input:

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

Example response:

{
  "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:

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

Important Ports

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

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.