google-maps-keyless-mcp 0.5.3__tar.gz

google_maps_keyless_mcp-0.5.3/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.github
+.venv
+.deps
+.artifacts
+**/__pycache__
+**/.pytest_cache
+**/.ruff_cache
+**/*.pyc
+tests
+scripts
+docs
+google-cookies.json
+.env

google_maps_keyless_mcp-0.5.3/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - run: make check

google_maps_keyless_mcp-0.5.3/.github/workflows/pypi.yml

@@ -0,0 +1,38 @@
+name: PyPI
+# A vX.Y.Z tag builds the wheel and sdist from the tagged tree and uploads them to PyPI as
+# `google-maps-keyless-mcp` with trusted publishing (OIDC through the `pypi` environment; no token is
+# stored). Tag pushes upload once the repository variable PYPI_PUBLISH is `true`; until then,
+# or to retry, run it by hand on the tag: `gh workflow run pypi.yml --ref vX.Y.Z`. Files that
+# are already on PyPI are skipped, so a repeated run is harmless.
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch: {}
+
+permissions: {}
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.ref_type == 'tag' && (github.event_name == 'workflow_dispatch' || vars.PYPI_PUBLISH == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Build
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          [ "${GITHUB_REF_NAME#v}" = "$version" ] || { echo "tag $GITHUB_REF_NAME is not version $version" >&2; exit 1; }
+          uv build
+      - name: Upload
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/

google_maps_keyless_mcp-0.5.3/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+# On a vX.Y.Z tag: test the tagged tree, build the image for linux/amd64 and linux/arm64
+# (dependency stage first, keyed on its inputs and reused), smoke-test it, then tag it
+# X.Y.Z and latest in ghcr.io/<owner>/google-maps-mcp, and publish a GitHub release.
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: read
+
+# GitHub can deliver one tag push twice: the runs of a ref queue one behind the other, and a
+# run whose tag already has a GitHub release (the last job) stops at `released`.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  released:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      done: ${{ steps.check.outputs.done }}
+    steps:
+      - id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          done=false
+          if [ "$GITHUB_REF_TYPE" = tag ] && gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            done=true
+            echo "$TAG is already released: nothing to do"
+          fi
+          echo "done=$done" >> "$GITHUB_OUTPUT"
+
+  test:
+    needs: released
+    if: needs.released.outputs.done != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - run: make check
+
+  image:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+      packages: write
+    env:
+      IMAGE: ghcr.io/${{ github.repository_owner }}/google-maps-mcp
+      PLATFORMS: linux/amd64,linux/arm64
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+      - uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build, smoke-test, tag
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          version="${VERSION#v}"
+          deps="$IMAGE:deps-$(sha256sum Dockerfile.deps requirements-runtime.lock | sha256sum | cut -c1-16)"
+          if ! docker buildx imagetools inspect "$deps" >/dev/null 2>&1; then
+            docker buildx build --platform "$PLATFORMS" -f Dockerfile.deps -t "$deps" --push .
+          fi
+          candidate="$IMAGE:sha-$(git rev-parse --short=12 HEAD)"
+          docker buildx build --platform "$PLATFORMS" -f Dockerfile --push -t "$candidate" \
+            --build-arg MAPS_MCP_DEPS_IMAGE="$deps" \
+            --build-arg VCS_REF="$GITHUB_SHA" \
+            --build-arg BUILD_DATE="$(git show -s --format=%cI HEAD)" \
+            --build-arg SOURCE_URL="https://github.com/$GITHUB_REPOSITORY" .
+          # Smoke: HTTP refuses to start without a bearer; stdio answers initialize.
+          rc=0
+          docker run --rm --network none --tmpfs /state:uid=1000 "$candidate" || rc=$?
+          [ "$rc" = 1 ] || { echo "expected a refusal without MCP_BEARER_TOKEN, got exit $rc" >&2; exit 1; }
+          reply="$(printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
+            | timeout 60 docker run --rm -i --network none --read-only --tmpfs /state:uid=1000 "$candidate" --transport stdio)"
+          grep -q '"serverInfo"' <<<"$reply" || { echo "stdio initialize failed" >&2; exit 1; }
+          docker buildx imagetools create -t "$IMAGE:$version" -t "$IMAGE:latest" "$candidate"
+
+  github-release:
+    needs: image
+    if: github.event_name == 'push' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --generate-notes

google_maps_keyless_mcp-0.5.3/.gitignore

@@ -0,0 +1,17 @@
+# secrets and local state
+google-cookies.json
+.env
+
+# python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# gate
+.deps/
+.artifacts/

google_maps_keyless_mcp-0.5.3/AGENTS.md

@@ -0,0 +1,22 @@
+# Working on google-maps-mcp
+
+Run `make bootstrap`, then `make check` (ruff, the format check, the lock-consistency check and
+pytest). After a dependency change run `make lock`: `requirements-runtime.lock` must equal
+`uv export` of `uv.lock`, because the image installs exactly that file.
+
+Tests never reach Google: the vendored library runs against recorded responses
+(`tests/conftest.py`, `tests/fixtures/README.md`). `tests/test_safety.py` is the boundary: a new
+host, a network import outside `google.py`, using more of the library (reviews, contacts,
+websites, login cookies), or a card view that loads or connects beyond its CSP is a deliberate
+change there, never a side effect.
+
+`src/maps_mcp/vendor/gmaps` is generated by `scripts/vendor-gmaps.sh`; never edit it here.
+Parsing fixes and new Google fields go to gmaps-scraper first (README "How it works").
+
+Probing Google live from a development machine is fine in small amounts: a handful of
+requests, paced, never in a loop. Re-record fixtures only with `scripts/capture-fixtures`,
+which scrubs per-request tokens, photo URLs and non-Google links; review the diff before
+committing it.
+
+Keep the code, comments, docs and fixtures free of personal details (names, addresses,
+accounts, hosts): this repository is public.

google_maps_keyless_mcp-0.5.3/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Issues and pull requests are welcome, especially when Google changes its responses and a tool
+starts failing with `schema_changed`.
+
+## Before you open a pull request
+
+```sh
+make bootstrap   # uv sync --locked
+make check       # ruff, format, lock consistency, tests (offline)
+```
+
+[AGENTS.md](AGENTS.md) has the rules: tests never reach Google, `tests/test_safety.py` is the
+boundary, `src/maps_mcp/vendor/gmaps` is generated by `scripts/vendor-gmaps.sh` (parsing fixes
+go to [gmaps-scraper](https://github.com/benjamin-di/gmaps-scraper) first), and fixtures are
+recorded only with `scripts/capture-fixtures`. Keep personal details (names, addresses,
+accounts) out of code, docs and fixtures.
+
+Security problems: see [SECURITY.md](SECURITY.md) instead of opening an issue.
+
+## How changes land
+
+Each release of this repository is exported from a private working repository as one
+`Release X.Y.Z` commit, so pull requests are not merged here: the next release would replace
+them. When a change fits, the maintainer applies it there, credits you in the release notes
+and closes the pull request with a link to the release that contains it. Issues are welcome;
+answers are best effort.

google_maps_keyless_mcp-0.5.3/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1.7
+# maps-mcp: source on top of maps-mcp-deps (Dockerfile.deps). The release workflow builds
+# both stages as one chain.
+ARG MAPS_MCP_DEPS_IMAGE=maps-mcp-deps:latest
+FROM ${MAPS_MCP_DEPS_IMAGE}
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE NOTICE THIRD_PARTY_NOTICES ./
+COPY src ./src
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install --system --compile-bytecode --no-deps . \
+    && rm -rf /app/src
+
+# /state (daily budgets, breaker, Google's consent cookies) is the only writable path; run the
+# container with a read-only root and a /state volume or tmpfs owned by uid 1000.
+RUN mkdir -p /state && chown 1000:1000 /state
+
+ARG VCS_REF=unknown
+ARG BUILD_DATE=unknown
+ARG SOURCE_URL=unknown
+LABEL org.opencontainers.image.title="maps-mcp" \
+      org.opencontainers.image.description="Read-only MCP server for Google Maps travel times, routes and places" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.source="${SOURCE_URL}" \
+      org.opencontainers.image.revision="${VCS_REF}" \
+      org.opencontainers.image.created="${BUILD_DATE}"
+
+ENV PYTHONUNBUFFERED=1 \
+    MAPS_HOST=0.0.0.0 \
+    MAPS_STATE_DIR=/state
+USER 1000:1000
+EXPOSE 8000
+ENTRYPOINT ["maps-mcp"]
+

google_maps_keyless_mcp-0.5.3/Dockerfile.deps

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1.7
+# Runtime dependencies for maps-mcp on a digest-pinned Python base. Kept apart from the
+# source so code-only releases reuse this layer: release.yml keys the image on this file and
+# requirements-runtime.lock. Rebuild it when dependencies change (make lock rewrites
+# requirements-runtime.lock) or when these pins are upgraded (deliberately, never a moving tag).
+FROM ghcr.io/astral-sh/uv:0.9.26@sha256:9a23023be68b2ed09750ae636228e903a54a05ea56ed03a934d00fe9fbeded4b AS uv
+
+FROM python:3.12.13-slim-trixie@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
+COPY --from=uv /uv /usr/local/bin/uv
+
+# The committed hash lock makes rebuilds independent of the package index's state.
+COPY requirements-runtime.lock /tmp/requirements-runtime.lock
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install --system --compile-bytecode --require-hashes -r /tmp/requirements-runtime.lock \
+    && rm -f /tmp/requirements-runtime.lock \
+    && python -c 'import httpx, PIL, fastmcp, tzdata; assert fastmcp.__version__ == "4.0.10"'
+
+ARG DEPS_REF=unknown
+LABEL org.opencontainers.image.title="maps-mcp-deps" \
+      org.opencontainers.image.revision="${DEPS_REF}"
+
+CMD ["true"]

google_maps_keyless_mcp-0.5.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 benjamin-di
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

google_maps_keyless_mcp-0.5.3/Makefile

@@ -0,0 +1,9 @@
+.PHONY: bootstrap check lock
+bootstrap:
+	./scripts/bootstrap.sh
+check:
+	./scripts/test.sh
+# After editing dependencies in pyproject.toml: refresh uv.lock and the image's hash lock.
+lock:
+	uv lock
+	uv export --frozen --no-dev --no-emit-project --no-header --quiet -o requirements-runtime.lock

google_maps_keyless_mcp-0.5.3/NOTICE

@@ -0,0 +1,22 @@
+maps-mcp
+Copyright (c) 2026 benjamin-di. Licensed under the MIT licence (LICENSE).
+
+Third-party code (full licence texts in THIRD_PARTY_NOTICES):
+
+- gmaps-scraper, https://github.com/nick-choudhary/gmaps-scraper. MIT License,
+  Copyright (c) 2026 Naveen. Vendored in src/maps_mcp/vendor/gmaps/ (with its LICENSE) from
+  the fork https://github.com/benjamin-di/gmaps-scraper at the commit in
+  src/maps_mcp/vendor/gmaps/VENDORED_COMMIT: upstream plus this project's contributions,
+  each offered upstream as a pull request (single exact-match search results, dated opening
+  hours with holiday flags, place details by place id, directions with steps and route
+  geometry, error classification in the HTTP transport). Only the modules maps-mcp runs are
+  vendored (the list is in scripts/vendor-gmaps.sh); contact and website extraction, the
+  CLI and its MCP server are left out.
+
+Acknowledgement: the request and response layout of Google Maps' directions endpoint was
+first documented by ai-ecoverse/skills (skills/gmaps, https://github.com/ai-ecoverse/skills,
+Apache-2.0, by Lars Trieloff). No code was copied; the facts were re-verified against live
+responses.
+
+Google Maps is a trademark of Google LLC. This project is not affiliated with, endorsed or
+sponsored by Google.

google_maps_keyless_mcp-0.5.3/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: google-maps-keyless-mcp
+Version: 0.5.3
+Summary: Read-only MCP server for Google Maps travel times, routes, places and map images, without an API key
+Project-URL: Repository, https://github.com/benjamin-di/google-maps-mcp
+Project-URL: Issues, https://github.com/benjamin-di/google-maps-mcp/issues
+Author: benjamin-di
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES
+Requires-Python: >=3.12
+Requires-Dist: fastmcp==4.0.10
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pillow>=12.0
+Requires-Dist: tzdata>=2025.2
+Description-Content-Type: text/markdown
+
+# google-maps-mcp
+
+A read-only [MCP](https://modelcontextprotocol.io) server that gives AI assistants Google Maps:
+**how long it takes to get from A to B** (driving with traffic, walking, cycling), **turn-by-turn
+directions**, **multi-stop route planning**, **places with their opening hours**, and **map
+images**, without an API key, billing or a Google account. It reads the same data the
+google.com/maps web page loads when you are signed out.
+
+Results use the field names of Google's official
+[Places API (New)](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places)
+and [Routes API](https://developers.google.com/maps/documentation/routes/reference/rest/v2/TopLevel/computeRoutes),
+so they read like those APIs' JSON. In clients that support MCP Apps (claude.ai, ChatGPT),
+routes and places are drawn as interactive cards.
+
+> Unofficial. Not affiliated with, endorsed or sponsored by Google. Automated access to
+> google.com/maps is not covered by Google's terms of service: use it for personal,
+> low-volume purposes, at your own risk (see [Terms and limits](#terms-and-limits)).
+
+## Tools
+
+| Tool | What it returns | Google requests |
+|---|---|---|
+| `maps_search_places(textQuery, latitude, longitude, radiusMeters, pageSize)` | Places like `places:searchText`: id, name, address, location, rating, review count, category, phone, website, price, time zone, `currentOpeningHours` | 1 |
+| `maps_get_place(id)` | One place by its id (`ChIJ…`), the same fields | 1 |
+| `maps_compute_route(origin, destination, intermediates≤8, travelMode, departureTime \| arrivalTime, computeAlternativeRoutes, includeSteps, includePolyline)` | Like `computeRoutes`: distance and duration per route and leg; for driving, duration in traffic (now or at the given time), typical duration, Google's range ("26–50 min") and the arrival or departure time; optional turn-by-turn steps and route line; a Google Maps link | 1 |
+| `maps_compute_route_matrix(origins, destinations, travelMode, departureTime)` | Like `computeRouteMatrix`, up to 25 pairs | 1 per pair |
+| `maps_plan_route(origin, stops≤8, destination \| roundTrip, travelMode, departureTime, dwellMinutes, optimizeOrder)` | A multi-stop plan: the fastest order, arrival and leave time per stop, whether each stop is open on arrival, warnings | 1 + up to 5 candidate orders + 1 per stop for hours |
+| `maps_show_route(...)` | The same plan as an interactive card | as `maps_plan_route` |
+| `maps_show_places(items[{id, note}]≤10, title)` | Place cards with photo, rating, open now, today's hours, holidays, links, and a pin map | 1 per place |
+| `maps_static_map(center, zoom, size, maptype, markers, route)` | A JPEG like the Static Maps API: an area, lettered pins and/or a route line; roadmap, satellite, hybrid or terrain | the lookups, plus about 10-25 map tiles |
+| `maps_status(check)` | Daily budgets, breaker, last error; `check=true` runs one real check (cached 55 min) | 0 (or 3) |
+
+Durations are Google's `"<seconds>s"` strings and distances are meters. Every key is present;
+`null` means Google did not say. Stops are a name or address, a place id from
+`maps_search_places`, or `"lat,lng"`; times are the local wall-clock time at the stop
+(`2026-10-29T08:30`).
+
+**Opening hours.** `currentOpeningHours` covers the next seven days with dates, so holiday
+hours land on the right day: `periods`, `weekdayDescriptions`, `openNow`,
+`nextOpenTime`/`nextCloseTime` (in the place's time zone), and `holidays`: the holiday Google
+attaches to a date, with `confirmed: false` when Maps only says it "might affect these hours".
+
+**Turn-by-turn.** `includeSteps` adds Routes API `steps` per leg (`navigationInstruction`
+{`maneuver`, `instructions`} such as "Turn left onto Gertrude-Fröhlich-Sandner-Straße",
+distance, time, start point, plus `notices` like "Toll road") and the grouped `segments` Maps
+lists ("Get on A4"). `maneuver` is Google's own code where the step carries one (ON_RAMP,
+MERGE, ROUNDABOUT_…, TURN_SLIGHT_RIGHT); it is never guessed from the text.
+
+**Multi-stop planning.** Google's web directions cannot reorder waypoints and a full
+travel-time matrix costs a request per pair, so `maps_plan_route` ranks every order of the
+stops by straight-line length, routes the four shortest plus the order given with real Google
+directions, and keeps the fastest (`savedVsGivenOrder` says what that saved). Stays
+(`dwellMinutes`) and traffic shift the arrival times; each stop's `openingStatus` is `open`,
+`closes_during_visit`, `closed` or `unknown`.
+
+**Cards.** `maps_show_route` and `maps_show_places` return their facts to the model, and MCP
+Apps hosts draw them with `ui://maps/view.html` (`src/maps_mcp/view.html`): a map built from
+Google Maps tiles in your browser (drag, zoom, map/satellite, fit) with the route and lettered
+pins, a stop timeline with arrival times and open/closed status, steps per leg and "Open in
+Google Maps"; or place cards with photo, rating, today's hours and links. The route line,
+steps and photos travel in the result's `_meta`, so they do not fill the model's context. The
+view loads only from www.google.com and lh3-6.googleusercontent.com, connects nowhere, sets
+every text as text and opens links through the host.
+
+## Quick start
+
+### Docker (HTTP)
+
+```bash
+docker run -d --name maps-mcp -p 127.0.0.1:8000:8000 \
+  -e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
+  --read-only --tmpfs /state:uid=1000 \
+  ghcr.io/benjamin-di/google-maps-mcp:latest
+```
+
+The MCP endpoint is `http://127.0.0.1:8000/mcp` (stateless streamable HTTP with JSON replies)
+with `Authorization: Bearer <token>`; `/health` is open. `MCP_BEARER_TOKEN` may hold several
+tokens separated by commas. For claude.ai or ChatGPT, put it behind HTTPS with a reverse proxy
+they can reach. Mount a volume on `/state` to keep the daily budgets and breaker across
+restarts.
+
+### stdio (Claude Desktop, Claude Code, Codex)
+
+```bash
+# from a checkout, with uv (https://docs.astral.sh/uv/)
+claude mcp add maps -- uv --directory /path/to/google-maps-mcp run maps-mcp --transport stdio
+# or with Docker
+claude mcp add maps -- docker run -i --rm --tmpfs /state:uid=1000 ghcr.io/benjamin-di/google-maps-mcp:latest --transport stdio
+```
+
+Outside Docker, state goes to `$XDG_STATE_HOME/google-maps-mcp` (else
+`~/.local/state/google-maps-mcp`); set `MAPS_STATE_DIR` to put it elsewhere.
+
+### Build the image yourself
+
+The image is two stages: the pinned dependencies (`Dockerfile.deps`) and the source on top.
+
+```bash
+docker build -f Dockerfile.deps -t maps-mcp-deps .
+docker build -t google-maps-mcp .
+```
+
+### Command line
+
+`maps-mcp [--transport http|stdio] [--host 127.0.0.1] [--port 8000]`: HTTP (the default)
+listens on 127.0.0.1:8000 (or `$MAPS_HOST`) and requires `MCP_BEARER_TOKEN`; the image sets
+`MAPS_HOST=0.0.0.0`.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MCP_BEARER_TOKEN` | (required for HTTP) | Accepted bearer token(s), comma-separated, each at least 32 characters |
+| `MAPS_HOST` | `127.0.0.1` (image: `0.0.0.0`) | HTTP listen address when `--host` is not given |
+| `MAPS_STATE_DIR` | per-user state dir (image: `/state`) | Budgets, breaker, Google's consent cookies |
+| `MAPS_DAILY_REQUEST_BUDGET` | `1000` | Requests to google.com per day, all tools together |
+| `MAPS_DAILY_TILE_BUDGET` | `3000` | Map tiles per day for `maps_static_map` |
+| `MAPS_BUDGET_TZ` | `UTC` | The time zone whose midnight resets the budgets |
+| `MAPS_MIN_INTERVAL_S` | `1.0` | Minimum seconds between requests (jittered ±30%) |
+| `MAPS_REQUEST_TIMEOUT_S` | `15` | Per-request timeout |
+| `MAPS_LANGUAGE` | `en` | Language of names and instructions |
+| `MAPS_CANARY_FROM` / `MAPS_CANARY_TO` | Wien Hauptbahnhof / Albertina | The status check's walk; `MAPS_CANARY_TO` must be a place id with opening hours |
+| `LOG_LEVEL` | `INFO` | JSON log lines on stderr; tool arguments are never logged, only short hashes |
+
+## How it works
+
+Four endpoints on www.google.com, the ones google.com/maps itself calls: `/search?tbm=map`
+(search), `/maps/preview/place` (place details), `/maps/preview/directions` (routes, steps
+and geometry) and `/maps/vt` (map tiles). Requests carry no account and no key; Google's
+consent cookies are fetched once and kept in the state directory. Parsing comes from
+[gmaps-scraper](https://github.com/nick-choudhary/gmaps-scraper), vendored in
+`src/maps_mcp/vendor/gmaps` from a fork that adds this project's contributions, each offered
+upstream as a pull request (see NOTICE). Refresh it with `scripts/vendor-gmaps.sh`; never edit
+the vendored copy by hand.
+
+It is a deliberately small, polite client: one request at a time, about one a second, daily
+budgets, results cached in memory (places 6 h, walking and cycling routes 12 h, driving
+10 min, or 1 h for a given time), and a breaker that stops all requests for 30 min, then 2 h,
+then 8 h when Google answers 429, `/sorry` or a sign-in wall.
+
+## Terms and limits
+
+- Google's terms of service do not allow automated access to google.com/maps. This project is
+  for personal, low-volume use; you are responsible for how you use it. If you need
+  guarantees, use Google's paid [Maps Platform APIs](https://developers.google.com/maps).
+- Do not store or redistribute Google's place data, and keep Google's attribution ("Map data
+  © Google") with maps, as the cards and images do.
+- Google can change its page format at any time. Parsing failures surface as
+  `schema_changed`, never as wrong numbers; please open an issue.
+- No walking or driving routes in South Korea (Google's own limit: `condition:
+  ROUTE_NOT_FOUND` with a note). Data in mainland China is thin. Opening hours are Google's: a
+  good secondary source, not proof.
+
+| Error code | Meaning |
+|---|---|
+| `blocked` | Google pushed back; the breaker is open (`maps_status` says until when) |
+| `schema_changed` | Google's response format changed; the tool cannot read it |
+| `upstream_error` | Network or Google failed after retries |
+| `waypoint_not_found` / `place_not_found` / `route_not_found` | The stop, the place id or a route could not be found; the message says which |
+| `budget_exhausted`, `busy`, `too_many_elements`, `invalid_argument`, `internal_error` | as named |
+
+## Development
+
+```bash
+make bootstrap   # uv sync
+make check       # ruff, format, lock consistency, tests
+```
+
+Tests never reach Google: the vendored library runs against responses recorded from
+google.com/maps (`tests/fixtures`, recorded and scrubbed by `scripts/capture-fixtures`; see
+`tests/fixtures/README.md`). `tests/test_safety.py` guards the boundary: the only host is
+www.google.com, and the card view loads only from its declared hosts and connects nowhere.
+
+Contributions: see `CONTRIBUTING.md`; security problems: `SECURITY.md`.
+
+## Credits
+
+Built on [gmaps-scraper](https://github.com/nick-choudhary/gmaps-scraper) (MIT). The directions
+request layout was first documented by
+[ai-ecoverse/skills](https://github.com/ai-ecoverse/skills) (`skills/gmaps`). See NOTICE and
+THIRD_PARTY_NOTICES. Licensed under the MIT licence (LICENSE).