google-maps-keyless-mcp 0.5.3__py3-none-any.whl

google_maps_keyless_mcp-0.5.3.dist-info/METADATA

@@ -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).

google_maps_keyless_mcp-0.5.3.dist-info/RECORD

@@ -0,0 +1,46 @@
+maps_mcp/__init__.py,sha256=XEhkFjdG_ywUhfYkq08gqtjApiFmdEfpW3Bp7jlSc7Q,328
+maps_mcp/__main__.py,sha256=3dYKHfmWsrdExFlTFlcR5a_icR9fAkn06Yh14TQkEd8,33
+maps_mcp/auth.py,sha256=z1A4sX_8RdiqXHskdu-6pED9x5avJyfOYr6OgdAZ_iY,1444
+maps_mcp/config.py,sha256=WmIB1Bpw-SFrCj2i-hDi08fvzVC8NIg_vK0jvy-8bwY,4945
+maps_mcp/errors.py,sha256=DWCuRGLSAKvx32_uBnR9NCN4Rq0YceEbOM8kC0yoJgE,2950
+maps_mcp/google.py,sha256=SiX011ZulzmqUhXwk1ACJO8Akj9d-RAVaC_9g2b1Fbk,9524
+maps_mcp/logs.py,sha256=x3TFOkPHRpZtH1dGipDx7EYA-HNn7ktj2lr1mp8y2SM,5480
+maps_mcp/planner.py,sha256=gZbUHwR30h21xw-l9YptJaJ-gEerbJEUILYj5gEu_Gg,1921
+maps_mcp/server.py,sha256=KcCg7HXKcjMoY-Uq6Pp01SfDNVqr7Fi2nL8qYK9UW2M,25130
+maps_mcp/service.py,sha256=Qpz417tbXDPY3gMGcxTeBfSkxLyJWhZiE5hwzrUQCRs,31631
+maps_mcp/shapes.py,sha256=c-wAdWJGtNXBgaHFCX3xYuuijc9gcQfe-cus87hHgtY,16288
+maps_mcp/state.py,sha256=KJpT8ecwTN7kW5MeXQGxuaExJ4cjr8LBFZAEnF_tGko,6212
+maps_mcp/staticmap.py,sha256=9cf_NCgo6jAUvcTLdZCuWM2YKur50abNnNXK9aCwsbI,6405
+maps_mcp/view.html,sha256=W9yx6QJR8P6JkHdj0ELd8cJw7PuhT_OE2KBW47178PY,30749
+maps_mcp/vendor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+maps_mcp/vendor/gmaps/LICENSE,sha256=oUiz9FNjnv2M-ecIoc0YgMMunLGtJnC4s2lvuAtItL8,1063
+maps_mcp/vendor/gmaps/VENDORED_COMMIT,sha256=qzkOMu0WpyUBd2BhXsc8X-Sxfp1C8poxiYtFGQCUCBI,41
+maps_mcp/vendor/gmaps/__init__.py,sha256=KhQ_CKegaaWvdroW7MAP8i8-HatKu-YTyLKSvsuccMc,839
+maps_mcp/vendor/gmaps/_directions.py,sha256=Q6_oZSMj4VLE-vDDhYV0DO4ihaOni8Ybd9UgNOfylV4,2633
+maps_mcp/vendor/gmaps/_hosts.py,sha256=uZcuMd0JPfKcd3PmKS1nU0A4cbeKMSCq7uV-Lq7_flE,766
+maps_mcp/vendor/gmaps/_places.py,sha256=jK_-iyJbHgb3JLY-Kt0jN3L1E3S4106Wn4gSf60RHEw,2360
+maps_mcp/vendor/gmaps/_reviews.py,sha256=HeUL8iMR5MqTSy7E0qr4UDaiYh8emJ2jH94M7OWqGKw,3305
+maps_mcp/vendor/gmaps/_search.py,sha256=pwqWLs3BD821fbvTnivYK4vh8TvcdqA1WMj0RTERGFs,54582
+maps_mcp/vendor/gmaps/client.py,sha256=54kiE9LSzhSS3hyyEK2S1V0QOVOaExCvPP-xqDMoGZw,12825
+maps_mcp/vendor/gmaps/control.py,sha256=DehEBqidDbaIionVFBXRoZFrz39SIrElVwO_FdobUnQ,9600
+maps_mcp/vendor/gmaps/exceptions.py,sha256=Uv7KEc4g6mPOdfKdLMMG0oJzpR3FoDsIePJm3L2SZj0,2595
+maps_mcp/vendor/gmaps/grid.py,sha256=387DT_nEXDfR4cuDEkFFRmqHDmL0VWVDRhuCzK3zDAk,6212
+maps_mcp/vendor/gmaps/transport.py,sha256=dnnsh-6Wr9196OBrTBHJ3_dwnVKlVzJj-726jtirJJY,16783
+maps_mcp/vendor/gmaps/validation.py,sha256=StJKbxdOskwkjhZFU9i7pRF7ZMvMdbI3kA3dy7HBztk,7380
+maps_mcp/vendor/gmaps/_auth/__init__.py,sha256=pewKmaJqfXt47AfgMHHKgNdw4uQLS0-qeSOpmjqvI04,345
+maps_mcp/vendor/gmaps/_auth/session.py,sha256=HKJ4XPHy0haB2l_Mn08tXr6IMPfZhu6IiaktlGRXm20,10392
+maps_mcp/vendor/gmaps/rpc/__init__.py,sha256=76h52dzjz4LArGKOnofWMnpOO57ep7qWw7ck-MpwOIA,1324
+maps_mcp/vendor/gmaps/rpc/decoder.py,sha256=D7um_8qvCa45c3sU5etNE8CdIi88vIqjx7oRFsho7-c,12761
+maps_mcp/vendor/gmaps/rpc/directions.py,sha256=zrt4irxhLXvxXjh4Kr4s1-ktmaB6EzJJKoJGQg6fYy4,20163
+maps_mcp/vendor/gmaps/rpc/encoder.py,sha256=GFh6MSL5-OQ5Dnrc5kMvz-SqLajJat_cKc56Rkouc0E,5021
+maps_mcp/vendor/gmaps/rpc/ids.py,sha256=Q6gEpAvHRxZba8k9DsnOZz5i0NhvsyJjHKck4l1ll3s,2066
+maps_mcp/vendor/gmaps/rpc/parser.py,sha256=xl2AsoYHKsK-pC4LymLkMCTeCuBPvx4M4apy3M3uOWk,42461
+maps_mcp/vendor/gmaps/rpc/pb_encoder.py,sha256=l4BELff1fhiuSuLl2iAXya9UsF_f7giZIYKHvRL-BOk,8114
+maps_mcp/vendor/gmaps/rpc/types.py,sha256=WrXwJAwFifDxO3sxvBvOIUMat6ITTyOIqivXLdbXOas,3602
+google_maps_keyless_mcp-0.5.3.dist-info/METADATA,sha256=8mcPuVOd7rqKGWB2sQ7CStVXAbU5_qQST0HcbUo3-Ms,11718
+google_maps_keyless_mcp-0.5.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+google_maps_keyless_mcp-0.5.3.dist-info/entry_points.txt,sha256=0Qj-62uHUkVSG0mDMag48E55xEKGjxnPO_Qf4-vHJpM,97
+google_maps_keyless_mcp-0.5.3.dist-info/licenses/LICENSE,sha256=R9rLPJhizyGD3Z958_ZKuwCeUq77gz732CEJq5rq-gw,1068
+google_maps_keyless_mcp-0.5.3.dist-info/licenses/NOTICE,sha256=YEx6Fx2SkxOZfakjl21cT_V-8Fv2gLFur5Ema64rmNc,1277
+google_maps_keyless_mcp-0.5.3.dist-info/licenses/THIRD_PARTY_NOTICES,sha256=6kGXu20Aw-Gbe3UhJ6_-vJd9SZTJxibZXfFt-VBg9QI,1462
+google_maps_keyless_mcp-0.5.3.dist-info/RECORD,,

google_maps_keyless_mcp-0.5.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

google_maps_keyless_mcp-0.5.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+google-maps-keyless-mcp = maps_mcp.server:main
+maps-mcp = maps_mcp.server:main

google_maps_keyless_mcp-0.5.3.dist-info/licenses/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.dist-info/licenses/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.dist-info/licenses/THIRD_PARTY_NOTICES

@@ -0,0 +1,30 @@
+Third-party code in maps-mcp, with its licence.
+
+1. gmaps-scraper
+   https://github.com/nick-choudhary/gmaps-scraper, vendored from
+   https://github.com/benjamin-di/gmaps-scraper at the commit in
+   src/maps_mcp/vendor/gmaps/VENDORED_COMMIT (upstream plus this project's pull requests),
+   in src/maps_mcp/vendor/gmaps/: only the modules maps-mcp runs (the list is in
+   scripts/vendor-gmaps.sh).
+
+MIT License
+
+Copyright (c) 2026 Naveen
+
+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.

maps_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""maps-mcp: walking/driving travel times and places from the signed-out Google Maps web page."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("google-maps-keyless-mcp")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0"

maps_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

maps_mcp/auth.py

@@ -0,0 +1,36 @@
+"""Bearer auth for the HTTP transport.
+
+``MCP_BEARER_TOKEN`` holds the accepted token, or several separated by commas (for example
+one for a reverse proxy and one for direct clients, so either can be rotated alone), each at
+least 32 characters. Only
+``/mcp`` is protected; ``/health`` stays open. The stdio transport needs no token.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+TOKEN_VAR = "MCP_BEARER_TOKEN"
+MIN_TOKEN_LENGTH = 32
+
+
+class AuthError(Exception):
+    """No token configured for a transport that requires one."""
+
+
+def bearer_auth_from_env(env: Mapping[str, str] | None = None) -> StaticTokenVerifier:
+    """A verifier accepting every configured token; raises AuthError when there is none."""
+    env = os.environ if env is None else env
+    tokens = [token.strip() for token in (env.get(TOKEN_VAR) or "").split(",") if token.strip()]
+    if not tokens:
+        raise AuthError(f"{TOKEN_VAR} must be set to serve over HTTP (comma-separated for several tokens)")
+    if any(len(token) < MIN_TOKEN_LENGTH for token in tokens):
+        raise AuthError(
+            f"each {TOKEN_VAR} token needs at least {MIN_TOKEN_LENGTH} characters (e.g. openssl rand -hex 32)"
+        )
+    return StaticTokenVerifier(
+        tokens={token: {"client_id": f"token-{index}", "scopes": []} for index, token in enumerate(tokens, 1)}
+    )

maps_mcp/config.py

@@ -0,0 +1,125 @@
+"""Settings from environment variables."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+class ConfigError(Exception):
+    """Bad or missing configuration; raised at startup only."""
+
+
+def default_state_dir(env: Mapping[str, str]) -> Path:
+    """Where state lives when MAPS_STATE_DIR is not set: the per-user state directory
+    ($XDG_STATE_HOME/google-maps-mcp, else ~/.local/state/google-maps-mcp). The container
+    image sets MAPS_STATE_DIR=/state."""
+    base = (env.get("XDG_STATE_HOME") or "").strip()
+    return (Path(base) if base else Path.home() / ".local" / "state") / "google-maps-mcp"
+
+
+@dataclass(frozen=True)
+class Settings:
+    state_dir: Path = Path("/state")
+    # Requests to google.com per day (in budget_tz), every tool together. A route or a place is
+    # one request; a matrix is one per pair. Keep it modest: it shares your IP's standing with
+    # anything else of yours that talks to Google.
+    daily_request_budget: int = 1000
+    # Map tiles (256 px images) per day for maps_static_map; a 640x480 map is about 12 tiles,
+    # cached in memory for a day.
+    daily_tile_budget: int = 3000
+    # The day the budgets count in (an IANA zone); they reset at its midnight.
+    budget_tz: str = "UTC"
+    # The canary's real check: a walk between two places and one place's details, given as
+    # place ids (or text). Defaults: Wien Hauptbahnhof -> Albertina, Vienna.
+    canary_from: str = "ChIJUU071tupbUcRyFdx20Nwgqg"
+    canary_to: str = "ChIJwVp-8psHbUcRuN43n5iK72Y"
+    # Minimum seconds between requests to Google (jittered +-30% by the library).
+    min_interval_s: float = 1.0
+    request_timeout_s: float = 15.0
+    language: str = "en"
+
+    @property
+    def cookie_file(self) -> Path:
+        return self.state_dir / "google-cookies.json"
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        env = os.environ if env is None else env
+        return cls(
+            state_dir=_state_dir(env),
+            daily_request_budget=_int(env, "MAPS_DAILY_REQUEST_BUDGET", 1000, 0, 100_000),
+            daily_tile_budget=_int(env, "MAPS_DAILY_TILE_BUDGET", 3000, 0, 100_000),
+            min_interval_s=_float(env, "MAPS_MIN_INTERVAL_S", 1.0, 0.2, 30.0),
+            request_timeout_s=_float(env, "MAPS_REQUEST_TIMEOUT_S", 15.0, 2.0, 60.0),
+            language=_language(env),
+            budget_tz=_zone(env, "MAPS_BUDGET_TZ", "UTC"),
+            canary_from=(env.get("MAPS_CANARY_FROM") or "").strip() or cls.canary_from,
+            canary_to=_place_id(env, "MAPS_CANARY_TO", cls.canary_to),
+        )
+
+
+def _int(env: Mapping[str, str], name: str, default: int, minimum: int, maximum: int) -> int:
+    raw = (env.get(name) or "").strip()
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ConfigError(f"{name} must be an integer") from None
+    if not minimum <= value <= maximum:
+        raise ConfigError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _float(env: Mapping[str, str], name: str, default: float, minimum: float, maximum: float) -> float:
+    raw = (env.get(name) or "").strip()
+    if not raw:
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ConfigError(f"{name} must be a number") from None
+    if not minimum <= value <= maximum:
+        raise ConfigError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _zone(env: Mapping[str, str], name: str, default: str) -> str:
+    raw = (env.get(name) or "").strip() or default
+    try:
+        ZoneInfo(raw)
+    except (ZoneInfoNotFoundError, ValueError):
+        raise ConfigError(f"{name} must be an IANA time zone such as Europe/Vienna") from None
+    return raw
+
+
+def _place_id(env: Mapping[str, str], name: str, default: str) -> str:
+    raw = (env.get(name) or "").strip() or default
+    if not raw.startswith("ChIJ"):
+        raise ConfigError(f"{name} must be a place id (ChIJ…) of a place with opening hours")
+    return raw
+
+
+def _state_dir(env: Mapping[str, str]) -> Path:
+    raw = (env.get("MAPS_STATE_DIR") or "").strip()
+    path = Path(raw).expanduser() if raw else default_state_dir(env)
+    try:
+        path.mkdir(parents=True, exist_ok=True, mode=0o700)
+        probe = path / ".write-test"
+        probe.write_text("")
+        probe.unlink()
+    except OSError:
+        raise ConfigError(f"the state directory {path} is not writable (set MAPS_STATE_DIR)") from None
+    return path
+
+
+def _language(env: Mapping[str, str]) -> str:
+    raw = (env.get("MAPS_LANGUAGE") or "").strip() or "en"
+    if not re.fullmatch(r"[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?", raw):
+        raise ConfigError("MAPS_LANGUAGE must be a language tag such as en, de or pt-BR")
+    return raw

maps_mcp/errors.py

@@ -0,0 +1,67 @@
+"""The error taxonomy. Tools report ``{code, next_step, retryable}`` and nothing else.
+
+Exception text never reaches a tool result: every message a model sees comes from the fixed
+``NEXT_STEP`` table below plus, for a few codes, our own detail text (which stop, which argument).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+NEXT_STEP: dict[str, str] = {
+    "invalid_argument": "Fix the arguments and call again.",
+    "place_not_found": (
+        "Google Maps has no place for this ID. Find the place again with maps_search_places and use the id it returns."
+    ),
+    "waypoint_not_found": (
+        "Google Maps could not find this stop. Make it more specific (add the city or the street), "
+        "or pass the place's id from maps_search_places or 'lat,lng'."
+    ),
+    "route_not_found": (
+        "Google Maps found no route connecting these stops in this mode (an island, a border, or a "
+        "country Google does not route in). Try another travelMode or other stops."
+    ),
+    "too_many_elements": "Ask for fewer origins x destinations (at most 25 pairs) or split the matrix.",
+    "blocked": (
+        "Google pushed back (rate limit, /sorry or captcha). No Google calls until the breaker closes "
+        "(maps_status shows when). Do not retry now."
+    ),
+    "budget_exhausted": (
+        "The daily Google request budget is spent. It resets at midnight (maps_status shows the day and zone)."
+    ),
+    "busy": "Other requests to Google are still running. Retry in a few seconds.",
+    "upstream_error": "Google Maps or the network failed after retries. Retry in a minute.",
+    "schema_changed": (
+        "Google Maps' response format changed and this tool cannot read it; other tools may still work. "
+        "Tell the person running this server: it needs an update."
+    ),
+    "internal_error": "maps-mcp failed unexpectedly. Retry once; if it repeats, tell the operator.",
+}
+
+RETRYABLE = frozenset({"busy", "upstream_error", "internal_error"})
+# The caller's own mistakes: routine, logged at INFO.
+AGENT_INPUT_CODES = frozenset(
+    {"invalid_argument", "place_not_found", "waypoint_not_found", "route_not_found", "too_many_elements"}
+)
+
+
+class MapsError(Exception):
+    """A classified failure. ``log_detail`` is for logs only."""
+
+    def __init__(self, code: str, detail: str | None = None, *, log_detail: str | None = None) -> None:
+        if code not in NEXT_STEP:
+            raise ValueError(f"unknown error code {code}")
+        super().__init__(code)
+        self.code = code
+        self.detail = detail
+        self.log_detail = log_detail
+
+    def payload(self) -> dict[str, Any]:
+        next_step = NEXT_STEP[self.code]
+        if self.detail:
+            next_step = f"{self.detail}. {next_step}"
+        return {"code": self.code, "next_step": next_step, "retryable": self.code in RETRYABLE}
+
+
+def invalid(detail: str) -> MapsError:
+    return MapsError("invalid_argument", detail)