maps-mcp

A small Model Context Protocol (MCP) server that answers commute and route questions using the Google Maps Directions API. It speaks MCP over stdio (same pattern as Cursor, Claude Desktop, and other MCP hosts).

Features

• Tool: get_transit_commute — Plans a route between two free-text places (addresses or neighborhoods) and returns a compact JSON summary.
• Travel modes — transit (default), driving, walking, or bicycling (passed as mode on the tool).
• Departure time — Optional ISO 8601 departure_time; if omitted, the server uses the current time (as a Unix timestamp for the Directions request).
• Structured output — The tool declares an MCP output schema. Results are returned as both human-readable JSON text and validated structured content (required by the MCP SDK when an output schema is present).

What the tool returns

The tool returns { routes: [...] } — an array of up to 3 alternative routes (Google's alternatives=true). Each route always includes:

• mode, duration_minutes, distance_km, summary, steps_count

When mode is transit, transit is filled with:

• segments — array of { line, vehicle_type } objects (e.g. [{ line: "N", vehicle_type: "TRAM" }, { line: "38", vehicle_type: "BUS" }])
• transfers, walking_minutes, first_departure, last_arrival

When mode is driving, driving is filled with:

• duration_in_traffic_minutes (when the API provides it), toll_roads

Other modes set transit and driving to null.

Having multiple routes lets the AI compare alternatives and pick the best one for the user's stated preference (e.g. fewest transfers, least walking, a specific line).

Google Cloud (Directions API + key)

In Google Cloud Console, pick or create a project, enable Directions API (APIs & Services → Library, search “Directions API”), then Credentials → Create credentials → API key. Link billing if Google requires it for your account.

Restrict the key under Credentials (recommended): API restrictions → limit to Directions API; Application restrictions → e.g. your server’s IP, or None only for quick local tests. Put the value in .env as GOOGLE_MAPS_API_KEY or in your MCP server env (see Setup and Connecting an MCP client).

Prerequisites

• Node.js 18+ (for global fetch).
• Make (optional) — only if you use the Makefile targets.
• Docker (optional) — only if you build or run the Docker image.

Setup

Step 1 — Get the code and install dependencies

cd maps-mcp
npm install

With Make:

cd maps-mcp
make install   # runs npm ci; use after cloning for a clean lockfile install

Step 2 — API key in the environment

Create a .env in the project root (see .env sample comments in-repo, or):

echo 'GOOGLE_MAPS_API_KEY=your-key-here' > .env

Or export for the current shell:

export GOOGLE_MAPS_API_KEY="your-key-here"

The app loads .env automatically on startup (import "dotenv/config" in src/index.ts) when the working directory is the project root.

Step 3 — Build (for compiled node runs)

npm run build

Or:

make build

Step 4 — Run the MCP server

See Running the server and Makefile.

Running the server

The process reads and writes MCP messages on stdin/stdout. Do not write logs to stdout; use stderr if you add logging, or the MCP stream will break.

| Goal | Command | |------|---------| | Dev (TypeScript, loads .env) | make dev | | Compiled run (make start runs build first) | make start |

Makefile commands

From the project root (requires make). Run make or make help for the full list.

| Command | What it does | |---------|----------------| | make install | npm ci (clean install from lockfile) | | make build | Compile TypeScript → dist/ | | make test | Unit tests + in-memory MCP e2e | | make test-live | Live Directions API test (needs GOOGLE_MAPS_API_KEY) | | make smoke | One real API request (needs key) | | make dev / make start | Run MCP server (dev / compiled) | | make docker-build | Build image (IMAGE=name:tag to override tag) | | make docker-run | Build + run with -i; export GOOGLE_MAPS_API_KEY in your shell first | | make docker-run-env | Build + run using --env-file .env |

Docker

You do not need Docker if you run Node on the host and point MCP at node/tsx. Use an image for isolation, reproducible deploys, or when you do not want a local Node install—stdio MCP still needs the host to run something like docker run -i … (or the Make targets below).

See the Dockerfile. make docker-build / make docker-run / make docker-run-env cover the usual flows; for a one-off: docker build -t maps-mcp:latest . then docker run --rm -i -e GOOGLE_MAPS_API_KEY="…" maps-mcp:latest.

Connecting an MCP client (example: Cursor)

Add a server entry that runs this project and passes the environment variable. Example shape (adjust paths and command to your machine):

{
  "mcpServers": {
    "maps-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/maps-mcp/dist/index.js"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-key-here"
      }
    }
  }
}

For development without building, you can use "command": "npx" with "args": ["tsx", "/absolute/path/to/maps-mcp/src/index.ts"] and the same env.

After the client loads the server, you should see the tool get_transit_commute in the tool list.

Development

Use make test, make test-live, and make smoke as needed; make lists every target.

Implementation notes

• Server name reported to MCP clients: google-maps-transit.
• If GOOGLE_MAPS_API_KEY is missing, the tool returns an MCP error with a clear message.
• Directions API failures (non-OK status, HTTP errors) surface as tool errors.
• Route alternatives are always requested (alternatives=true); up to MAX_ROUTES = 3 are returned. Google may return fewer if no alternatives exist.