MCP AI Agent with Google ADK, Google Maps, and Opik

Video Demonstration

<div align="center"> <a href="https://www.youtube.com/watch?v=fh0lkWitz2E"> <img src="https://img.youtube.com/vi/fh0lkWitz2E/maxresdefault.jpg" alt="Watch the Demo" style="width:80%;"> </a> Click the image above to watch the demo on YouTube </div>

This project demonstrates the creation of an AI Agent using the Google Agent Development Kit (ADK), OpenAI's GPT-4o model, the Google Maps MCP Server, and Opik for observability with Comet.ml.

The primary goal of this project is to deepen my understanding of Agent Development principles, the application of the Model Context Protocol in practice, and how to integrate its tools and services into an AI Agent for enhanced abilities beyond the training data.

This project is largely inspired by Santiago Valdarrama's tutorial on YouTube:

Video: Building AI Agents with Google's Agent Development Kit (ADK)
Repo: svpino/google-adk-sample

Key Technologies
Project Structure
Project Setup and Installation
Screenshots & Usage
Code Deep Dive (agent.py)
Author
License

Key Technologies

Google Agent Development Kit (ADK)

ADK logo

The Google Agent Development Kit (ADK) is a Python framework designed to simplify the development of AI Agents powered by LLMs. It provides access to tools, memory, agent orchestration and LLMs from providers like OpenAI, Anthropic, Cohere and many others through integration with the LiteLlm library. The ADK also includes a web UI for interacting with and debugging agents.

Opik & CometML

Opik is an open-source observability solution for LLM applications, built by Comet. It allows you to trace, visualize, and debug the interactions within your AI Agents, including LLM calls, tool usage, and other operations. In this project, Opik is configured to send traces to CometML, providing a rich UI to inspect agent behavior.

Model Context Protocol (MCP)

MCP

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs and connect them to different data sources and tools. It defines a schema for tool descriptions, invocations, and responses. This allows for interoperability between different LLM systems and tool providers.

Google Maps MCP Server

The Google Maps MCP Server is a Node.js application that exposes Google Maps Platform APIs as MCP tools. This allows an ADK Agent to easily leverage Google Maps features to deliver more relevant, context-aware responses.

How it runs: The ADK's MCPToolset can automatically start this server using npx if it's not already running, as configured in this project.
Main Tools Exposed:
- maps_directions: Get driving, walking, or cycling directions.
- maps_geocode: Convert addresses to geographic coordinates.
- maps_reverse_geocode: Convert geographic coordinates to addresses.
- maps_elevation: Get elevation for a given coordinate.
- maps_search_places: Search for places (e.g., restaurants, landmarks).
- maps_place_details: Get detailed information about a specific place.
- maps_distance_matrix: Calculate travel time and distance between multiple origins and destinations.

Project Structure

.
├── assets
│   └── screenshots
│       ├── interface.png
│       ├── maps_direction_tool_input_output.png
│       ├── maps_direction_tool_opik.png
│       ├── maps_direction_tool.png
│       ├── maps_directions_tool_events.png
│       ├── maps_elevation_tool.png
│       ├── maps_place_details_event.png
│       ├── maps_reverse_geocode_event.png
│       ├── opik_overall_input_output.png
|       ├── adk.png
|       ├── mcp.png
│       └── opik_traces.png
├── examples
│   └── agent_conversation.yaml
├── LICENSE
├── mcp_agent
│   ├── __init__.py
│   └── agent.py
├── pyproject.toml
├── README.md
└── uv.lock

Project Setup and Installation

Prerequisites

Python 3.11
uv (Python package and virtual environment manager)
Node.js and npm / npx (required to run the Google Maps MCP Server, which the ADK will start via npx)
A Google Maps Platform API Key?
An OpenAI API Key.
CometML API Key, Project ID, and Workspace.

Installation Steps

Clone the repository:

git clone https://github.com/luuisotorres/mcp-ai-agent.git
cd mcp-ai-agent

Create and sync the virtual environment using UV:

uv venv  # Create a virtual environment (e.g., .venv)
uv sync  # Install dependencies from pyproject.toml
source .venv/bin/activate # Or `.\.venv\Scripts\activate` on Windows

Set up environment variables: Copy the example environment file and fill in your credentials:
```
cp .env.example .env
```
Then, edit .env with your actual API keys.

Environment Variables

GOOGLE_MAPS_PLATFORM_API_KEY="your-google-maps-api-key"
OPENAI_API_KEY="your-openai-api-key"
COMET_API_KEY="your-comet-api-key"
COMET_WORKSPACE="your-comet-workspace"
COMET_PROJECT_NAME="your-comet-project-name"

The .env file should contain:

GOOGLE_MAPS_PLATFORM_API_KEY: Your Google Maps Platform API key.
- Purpose: Allows the Google Maps MCP Server to make requests to Google Maps APIs.
OPENAI_API_KEY: Your OpenAI API key.
- Purpose: Allows the LiteLlm model to use OpenAI's GPT models.
COMET_API_KEY: Your CometML API Key.
- Purpose: For Opik to send traces to your CometML project.
COMET_WORKSPACE: Your CometML workspace.
COMET_PROJECT_NAME: The CometML project name where traces will be stored.

Running the Agent

Once the setup is complete, run the ADK web UI:

uv run adk web

This command will:

Start a FastAPI server.
Provide a web interface at http://127.0.0.1:8000 to interact with your agent.
The MCPToolset in agent.py is configured to start the Google Maps MCP server via npx automatically when the agent needs to use its tools.

Screenshots & Usage

ADK Web UI

Upon running uv run adk web and navigating to http://127.0.0.1:8000 (or the port shown in your terminal), you'll see the ADK Web UI. You can select your Agent, in this case mcp_agent, and start a conversation.

(Screenshot 1: The initial ADK Web UI screen with the chat input.) Caption: The main interface of the ADK Web UI where you can type messages to your agent.

Agent Using Tools

The agent can understand requests for directions, place details, elevation, and more, using the tools from the Google Maps MCP Server.

Example: Getting Directions The agent responds to "How do I drive from São Paulo to Campinas?" with turn-by-turn directions.

(Screenshot 2: Agent using the maps_directions tool.) Agent Directions Caption: The agent successfully uses the maps_directions tool to provide driving directions in the chat interface.

Example: Getting Place Details The agent can fetch reviews and other information for landmarks.

(Screenshot 3: Agent using maps_place_details for Eiffel Tower reviews.) Place Details Event/UI Caption: Agent fetching and displaying reviews for the Eiffel Tower, showcasing the maps_place_details tool usage and output.

Example: Getting Elevation The agent can provide elevation for given coordinates.

(Screenshot 4: Agent using maps_elevation tool.) ![Elevation Tool UI](assets/screens

MCP AI Agent

Install / Use

README