Google Maps MCP Server

This server is a remote Model Context Protocol (MCP) server for Google Maps. It finds places, gives place details, and plans routes. It uses the Google Maps Platform Places API (New) and Routes API.

The server runs on Cloudflare Workers and on Bun. It is built on the MCP server template, version 2.1, and the official MCP TypeScript SDK 2.3.0. It uses protocol version 2026-07-28. It also accepts clients that use the 2025 protocol versions.

The server is for agents that know the location of the user, for example on a watch or a phone. The client gives the current position, and the model can:

• Find places near the user, by type or by name.
• Read the opening hours, ratings, reviews, contact data, and photos of a place.
• Get walking, driving, cycling, or transit directions.
• Compare the distance to several destinations.

Tools

Each tool gives text for the model and structured data. The tool descriptions give all inputs and outputs. All tools only read data.

Examples of requests:

• “Coffee near me”: search_places with types: ["cafe"] and open_now: true.
• “Is the pharmacy on Main Street open?”: search_places, then get_place with fields: ["hours"].
• “Which is closer, A or B?”: get_route with both places as destinations.

Photo results contain public image URLs that Google makes for each request. They never contain the API key.

Connect a client

The server URL is the deployed Worker’s MCP_PUBLIC_URL, for example https://google-maps..workers.dev/mcp. Use the Streamable HTTP transport, and send the shared token in the Authorization header.

The client must give the model the current location of the user and the current time. The tools use both.

Authentication

Production uses AUTH_MODE=bearer. All clients send the same secret token, BEARER_TOKEN, as Authorization: Bearer . The server compares the token in constant time. A request without the correct token gets 401. The server publishes no OAuth documents, so clients do not try to sign in.

The Google API key (API_KEY) is a different secret. The server sends it to Google only, in the X-Goog-Api-Key header. The server never accepts a key from a client, and it never sends the client’s token to Google.

For the authentication modes of the template, refer to the template’s docs/auth.md.

Configuration

The server identity (name, version, and instructions) is in src/server.ts. The deployment settings are environment variables. On Workers, the production values are in wrangler.production.jsonc, which is gitignored; wrangler.production.example.jsonc shows its shape.

.env.example describes all variables for Bun. If the configuration is not valid, Bun does not start, and a Worker answers 500 {"error":"server_misconfigured"} to all requests. The log gives each problem.

Set up Google Maps Platform

1. In the Google Cloud console, select or create a project.
2. Enable Places API (New) and Routes API.
3. Create an API key. Restrict it to these two APIs.
4. Store the key as the API_KEY secret.

For the requests that the server sends to Google, refer to docs/google-maps.md.

Deployment

bun run deploy deploys the google-maps Worker with wrangler deploy --config wrangler.production.jsonc. Before you deploy, read docs/deploy.md. It gives the secret names and the checks to do after a deployment.

Development

1. Install the dependencies:

   bun install
   

2. Copy .env.example to .env. Set API_KEY.

3. Start the server:

   bun run dev
   

The server URL is http://127.0.0.1:3000/mcp. To use the Cloudflare local runtime, put API_KEY in .dev.vars and run bun run dev:worker. The URL is then http://127.0.0.1:8787/mcp.

The tests do not send requests to Google. tests/contract.test.ts makes sure that the tool names and input schemas do not change. tests/routes.test.ts makes sure that each public route gives the same status as before the template migration.

Project structure

src/
  server.ts       Server identity, dependencies, McpServer factory
  settings.ts     API_KEY and the test-only Google origin
  tools/          search_places, get_place, get_route. index.ts gives the order.
  services/       google-maps.ts: the Places API and Routes API client
  platform/       Template code. Do not change it.
  bun.ts          Entry point for Bun
  worker.ts       Entry point for Cloudflare Workers
tests/            Tool, service, contract, and route tests, and the template's platform tests
scripts/          Smoke tests and the loopback Google mock

For the template’s design, refer to its docs/architecture.md and docs/tools.md.

License

MIT