goplaces MCP
Provides tools for interacting with Google Places API (New) and Google Routes API, enabling place search, nearby search, autocomplete, place details, photos, place resolution, directions, and route search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@goplaces MCP find coffee shops near me in Austin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
goplaces MCP
Google Places and Routes tools for Codex, Claude Code, and Hermes Agent, served by one stdio Model Context Protocol server.
An agent with this server can search for businesses and landmarks, look up hours, phone numbers, reviews, and photos, and calculate directions, travel-time comparisons, and stops along a route, all from live Google data.
Quick start
You need Python 3.11 or newer, uv, and a
Google Cloud API key with Places API (New) enabled. Enable the Routes
API on the same project as well if you want directions, route search, or
travel-time matrices.
Clone the repository and install the locked dependencies:
git clone https://github.com/jrajasekera/goplaces-mcp cd goplaces-mcp uv syncCheck that the server starts with your key:
export GOOGLE_PLACES_API_KEY=your_google_api_key uv run goplaces-mcpThe server speaks MCP over stdin and stdout and waits silently for a client. Nothing is printed, and no Google request is made. Press
Ctrl-Cto stop it.Register it with a host using one of the sections under Install into a host. The host launches the server itself from then on. You never run it by hand.
Related MCP server: Google Maps Geocoding MCP Server
Install into a host
Every host launches the same goplaces-mcp command and passes it
GOOGLE_PLACES_API_KEY plus any of the optional variables.
The bundled skill in skills/goplaces/SKILL.md teaches the agent when to reach
for which tool and how to keep Google costs down.
Codex
This repository is a Codex plugin. .codex-plugin/plugin.json registers the
skill and the shared .mcp.json server definition.
Install it through a Codex plugin marketplace, or point Codex at the
.mcp.json file in a local checkout. The MCP child process inherits
GOOGLE_PLACES_API_KEY and the optional variables from the Codex environment,
so set them in the shell that starts Codex.
Claude Code
This repository is also a Claude Code plugin. Claude Code discovers
.claude-plugin/plugin.json, the root .mcp.json, and the skill when the
plugin is installed.
To use a local checkout without installing it:
export GOOGLE_PLACES_API_KEY=your_google_api_key
claude --plugin-dir /absolute/path/to/goplaces-mcpThe server inherits the key from the environment Claude Code starts in.
Hermes Agent
Hermes has its own MCP client, so it uses this server directly rather than a
native plugin. The older standalone hermes-goplaces plugin is retired.
Clone the repository on the Hermes host and run
uv syncin it.Add one
mcp_serversentry to~/.hermes/config.yaml:mcp_servers: goplaces: command: /usr/local/bin/uv args: - run - --frozen - --directory - /absolute/path/to/goplaces-mcp - goplaces-mcp env: GOOGLE_PLACES_API_KEY: ${GOOGLE_PLACES_API_KEY}Two details matter here. Hermes passes only an allowlist of variables (
PATH,HOME, and similar) to stdio subprocesses, so the key must be named underenv. The${VAR}form resolves from~/.hermes/.env, which keeps the key out ofconfig.yaml. Use an absolute path foruvbecause the entry has no working directory and the inheritedPATHmay differ from your login shell's.Copy the skill next to it:
cp -R skills/goplaces ~/.hermes/skills/goplacesVerify the connection without spending any Google quota:
hermes mcp test goplaces
Hermes registers the tools into an mcp-goplaces toolset and prefixes each
name with mcp_ and the server name, much as Claude Code prefixes MCP tools.
The agent therefore sees a longer name than the bare one used in this README.
Hermes also decodes the image block from goplaces_photo into a MEDIA:
attachment.
Tools
All ten tools are read-only. Place-returning tools accept detail_level, which
sets the Google field tier described under Cost.
Tool | Use it when |
| Free-form text search for businesses, landmarks, venues, or services, with filters such as open now, rating, and price. |
| You already have coordinates and a radius, optionally filtered by place type. |
| Turning partial user input into place and query suggestions with place IDs. |
| One place ID needs phone, website, hours, business status, reviews, or photo metadata. |
| Fetching the image for a photo name returned by |
| Turning an address, landmark, or city into candidate place IDs and coordinates. |
| Distance, duration, warnings, and optional steps between two points. Modes: drive (default), walk, bicycle, transit. |
| Stops such as charging, fuel, coffee, or hotels along a route, ranked by detour time. |
| Ranking several destinations by travel time from one or more origins in a single request. |
| Finding out what is at a latitude and longitude, nearest first. |
Directions, route search, and route matrix use the Routes API. The rest use the Places API (New).
Every tool publishes a title, an input schema, and an output schema through MCP,
and results arrive as structuredContent. The authoritative definitions live in
src/goplaces_mcp/schemas.py.
Configuration
The server reads its configuration from environment variables. Only the API key is required.
Variable | Default | Purpose |
| none, required | Google Cloud API key with Places API (New) enabled. |
|
| Per-request HTTP timeout. |
|
| Total attempts for a request that returns |
|
| Base delay for exponential backoff between attempts. |
| off | Set to |
|
| Places endpoint. For controlled testing only. |
|
| Routes endpoint. For controlled testing only. |
| same as | Directions endpoint. For controlled testing only. |
Cost
Google bills each Places request at the most expensive field tier named in its
field mask, so the fields a tool asks for decide what a call costs. The
detail_level argument picks the tier:
| Fields returned | Google tier |
| place IDs only | Essentials |
| name, address, location, type, Maps link | Pro |
| adds rating, price, hours, phone, website | Enterprise |
Two further options add the Enterprise + Atmosphere tier and are off by
default: include_atmosphere (editorial summary, dine-in, takeout, delivery,
accessibility, parking) and include_ev (charging connectors).
The default stays full so that responses never silently lose fields. The
bundled skill tells agents to ask for basic when ratings and hours are not
needed, and for ids when results only feed another call.
A field that was not requested is absent from the response rather than empty.
A missing rating means the tier did not ask for it, not that the place is
unrated.
Errors and retries
Errors are returned to the agent as JSON with an error object and are flagged
as tool errors over MCP. Handler exceptions never escape the transport.
{"error": {"type": "validation", "field": "location.radius_m", "message": "must be > 0"}}
{"error": {"type": "google_api", "status": 403, "message": "..."}}validationerrors are raised before any Google request is made, so a bad argument costs nothing.google_apierrors carry Google's HTTP status and message.Responses with status
429or503are retried with exponential backoff up toGOOGLE_PLACES_MAX_ATTEMPTS. Every other status fails immediately.A missing
GOOGLE_PLACES_API_KEYis reported as a validation error naming the variable.
How it fits together
One server, three hosts. Codex and Claude Code both read the root
.mcp.json. Its launcher shells through /bin/sh to expand
${CLAUDE_PLUGIN_ROOT:-.}: Claude Code supplies that variable, Codex does not,
and the fallback to the working directory covers Codex. That is why one
manifest serves both hosts, and also why the launcher is POSIX-only. Windows
hosts cannot start it as written. Hermes needs no manifest because it has its
own MCP client and takes the command from its config file.
Frozen startup. The launcher runs uv run --frozen, so starting the server
never resolves or re-locks dependencies. Startup stays fast and deterministic.
Thin adapter, thick client. src/goplaces_mcp/server.py only translates
between MCP and the handlers: it attaches read-only annotations, sets isError
on payloads carrying an error key, returns structuredContent, and lifts
photo bytes into an image block. Everything Google-specific, including
validation, field masks, retries, and response mapping, lives in
src/goplaces_mcp/tools.py. The client depends only on the MCP transport
package.
Validate before you pay. Every argument is checked before the first billable request, and a tool that issues several requests builds all of them before sending any. A mistake in the second request is caught before the first one has cost anything.
Development
uv sync --dev
uv run pytestTests never need credentials and never call Google. tests/fake_google.py
runs a localhost HTTP server that replays canned Google JSON, wired in through
the base-URL variables above, so handler tests exercise the real
request-building and response-mapping code.
tests/test_protocol_results.py checks each tool's real output against the
output schema it publishes, and tests/test_server.py covers tool listing,
annotations, server instructions, error flagging, and both plugin launch modes.
Before handing off a change that touches packaging, schemas, the server, or the manifests, also run:
uv run python -m compileall -q src tests
uv build
git diff --check
claude plugin validate .AGENTS.md records the project's compatibility invariants and the traps that
have produced defects before. Read it before changing a handler.
Attribution and license
The Google client was converted from OpenClaw goplaces by Peter Steinberger.
See THIRD_PARTY_NOTICES.md.
Google's terms require attribution when reviews or photos are shown. The responses carry the author attribution, and the bundled skill tells agents to keep it.
MIT licensed. See LICENSE.
Available Tools
10 toolsgoplaces_autocompleteAutocomplete a placeARead-onlyIdempotent
Autocomplete a partial place or query string using Google Places. Use to turn partial user input into place/query suggestions and place IDs.
Inputs: input (required), lat, lng, limit, +4 more. Returns: error, suggestions
goplaces_detailsPlace detailsARead-onlyIdempotent
Fetch rich Google Place Details by place ID. Use after search, nearby, autocomplete, or resolve when the user needs phone, website, hours, business status, reviews, or photos. Reviews and photos are opt-in because they are heavier fields.
Inputs: place_id (required), region, language, include_ev, +4 more. Returns: name, error, hours, phone, +28 more
goplaces_directionsGet directionsARead-onlyIdempotent
Get directions, distance, duration, warnings, and optional steps between two locations using Google Routes. Each endpoint can be specified by text, place ID, or latitude/longitude. Supports walk, drive, bicycle, transit, units, departure/arrival time, drive avoid modifiers, and one compare mode.
Inputs: mode, units, region, to_lat, +20 more. Returns: legs, mode, error, steps, +11 more
goplaces_nearbySearch near coordinatesBRead-onlyIdempotent
Search Google Places near a latitude/longitude within a radius. Use when the user gives coordinates or you already resolved a location. Returns compact place summaries.
Inputs: lat (required), lng (required), radius_m (required), limit, +11 more. Returns: error, results
goplaces_photoResolve a place photoARead-onlyIdempotent
Resolve a Google Places photo resource name into a photo media URL. Use with photo names returned by goplaces_details(include_photos=true).
Inputs: name (required), max_width_px, include_image, max_height_px. Returns: name, error, photo_uri, image_mime_type
goplaces_resolveResolve a locationARead-onlyIdempotent
Resolve a free-form location string into candidate Google places with coordinates and place IDs. Use before nearby searches or directions when you need structured candidates for an address, landmark, city, or venue.
Inputs: location_text (required), limit, region, language. Returns: error, results
goplaces_reverse_geocodeIdentify a coordinateARead-onlyIdempotent
Identify what is at a latitude/longitude by finding the nearest places, closest first, with the distance from the point. Use for 'what is at these coordinates' or to label a GPS position.
Inputs: lat (required), lng (required), limit, region, +6 more. Returns: error, results, query_location
goplaces_route_matrixCompare travel timesARead-onlyIdempotent
Rank destinations by travel time and distance from one or more origins in a single request. Use for 'which of these is closest to home' or 'how long to each of these three offices' instead of one directions call per candidate. Results are sorted fastest first.
Inputs: origins (required), destinations (required), mode, units, +3 more. Returns: mode, error, results
goplaces_route_searchFind stops along a routeARead-onlyIdempotent
Find places along a route between two locations, ranked by how little they detour from it. Returns each result's detour time plus the direct route's distance and duration. Use for requests like 'coffee stops between Seattle and Portland' or 'EV charging on the way to Portland'.
Inputs: query (required), to_text (required), from_text (required), mode, +10 more. Returns: error, route, results
goplaces_searchSearch placesARead-onlyIdempotent
Search Google Places by free-form text. Use for finding businesses, landmarks, venues, restaurants, shops, attractions, or services. Supports filters for open now, rating, price, type, pagination, and optional circular location bias. Returns compact place summaries and a next_page_token when Google provides one.
Inputs: query (required), lat, lng, limit, +17 more. Returns: error, results, next_page_token
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target clearly distinct actions (directions, photo, details, route_matrix), but search/resolve/autocomplete all convert text into places, and nearby/reverse_geocode both find places near coordinates. Descriptions provide use-case cues, so an agent can usually pick correctly, but the boundaries are not perfectly sharp.
All tools share the goplaces_ prefix and snake_case naming with clear action/resource terms. There is no mixing of conventions such as camelCase, hyphens, or vague names.
10 tools are well-scoped for a Google Places/Routes MCP, covering distinct API surfaces without obvious filler. Each tool maps to a meaningful location or routing capability.
The set covers search, nearby, autocomplete, details, photos, resolution, directions, route search, route matrix, and reverse geocoding. For a read-only places/routes domain, this provides comprehensive workflow coverage with no major dead ends.
Maintenance
Related MCP Connectors
Routing, geocoding, places, matrix and map tools for location-aware AI workflows.
Geocode, reverse-geocode, autocomplete, route and search places.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Location tools for Claude and other MCP clients, strongest in the US and Great Britain. Geocode whole lists with a confidence score per row, filter by distance, get road distances and drive-time areas, and plan multi-driver routes with Google Maps links. Check flood zones, crime and live warnings, find nearby places and UK registers (NHS, CQC, food hygiene), and keep shareable maps. Reads and writes Google Sheets. Free: sign in with Google.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to access Google Maps services including geocoding, place search, directions, distance calculations, and elevation data through stdio communication. Provides comprehensive location-based functionality with direct Google Maps API integration.MIT
- AlicenseAqualityDmaintenanceEnables LLM clients to convert addresses to coordinates (forward geocoding), coordinates to addresses (reverse geocoding), and lookup Google Place IDs using the Google Maps Geocoding API with support for multiple languages and advanced filtering.39 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides custom tools to the Gemini model for spatially grounding responses using Google Maps Platform APIs (Places, Routes, Elevation).71Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Google Maps API for geocoding, place search, directions, distance matrices, and elevation data through natural language.19 PyPIMIT