Google Maps MCP Server

Overview

Python-based MCP server delivering routing and geocoding utilities backed by the Google Maps Platform. It is packaged as the Docker image expected by google-maps.mcp.yml (mcp/google-maps) and exposes three tools over STDIO via FastMCP.

Components

• main.py – instantiates the MCP server, registers tools, and routes calls to google.py helpers.
• google.py – wraps the googlemaps SDK to execute Directions, Geocoding, and Reverse-Geocoding requests.
• pyproject.toml – defines the runtime dependencies (mcp, googlemaps).
• Dockerfile – two-stage Python 3.13 build that vendors dependencies in a slim image and runs python3 main.py as user mcp.

Exposed MCP tools

Tool	Purpose	Input
calculate_route	Returns the duration between two addresses.	origin, destination, travel_mode (driving, walking, bicycling, transit), optional arrival_time (epoch seconds).
get_coordinates	Geocodes an address into (lat, lng).	address.
get_address	Reverse geocodes coordinates into a human-readable address.	coordinates tuple (lat, lng).

All tools return the response from the Google Maps client (dict/tuple) so the MCP host receives structured JSON.

Configuration

The Docker host definition mcp_servers/google-maps.mcp.yml launches the container and injects the API key:

google-maps:
  transport: stdio
  command: docker
  args:
    - run
    - --init
    - -i
    - --rm
    - --network
    - buddai_net
    - -e
    - GOOGLE_MAPS_API_KEY
    - mcp/google-maps
  env:
    GOOGLE_MAPS_API_KEY: "${GOOGLE_MAPS_API_KEY}"

Set GOOGLE_MAPS_API_KEY in the MCP host environment (server-side). The code reads it from os.getenv at module import time, so the variable must be present when the process starts.

This service uses HTTPS only and requires outbound Internet access to reach Google’s endpoints. No database connectivity is needed.

Running locally

1. Install Python ≥ 3.11 with pip.
2. Create a virtualenv and run pip install -r <(pipenv export) is not provided; instead install directly: pip install mcp==1.9.4 googlemaps==4.10.0.
3. Export GOOGLE_MAPS_API_KEY to a valid API key with Directions/Geocoding enabled.
4. Run python main.py to expose the MCP server over STDIO.

Docker usage

Build the image (optional if you consume the pre-built mcp/google-maps):

docker build -t mcp/google-maps mcp_servers/drive

Run it the same way as the host definition:

docker network create buddai_net                  # once
GOOGLE_MAPS_API_KEY=your-key \
docker run --rm --init -i \
  --network buddai_net \
  -e GOOGLE_MAPS_API_KEY \
  mcp/google-maps

The container responds on STDIO; wrap it with langchain_mcp_adapters or a compatible MCP client.

Development notes

• main.py currently registers the server name as "Weather MCP Server"; update it if you rely on the server metadata.
• The Google Maps client performs live API calls—mock the SDK for tests to avoid quota consumption.
• arrival_time must be an epoch timestamp (seconds). Leave it unset to retrieve current ETA.

Troubleshooting

• REQUEST_DENIED errors: check that the API key allows required services and that the container has network access.
• No route found: the helper raises an exception if Directions returns an empty list; handle this in the caller or verify the addresses/mode.
• Reverse geocoding failures: ensure coordinates are within supported ranges and the API key has Geocoding enabled.