MCP 服务器

Route & Gas Station MCP Server

Enables users to query driving distances and find gas stations along routes using Google Maps APIs through natural language, powered by FastMCP and Google ADK.

README

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

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

Open Google Cloud Console
Create a new Google Cloud project
Link a billing account
Enable the following APIs:
- Routes API
- Places API (New)
Go to APIs & Services -> Credentials
Create an API key
Restrict the key to only:
- Routes API
- Places API (New)
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