Route & Gas Station Server

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

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.

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:

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

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.