{"id":49598972,"url":"https://github.com/arthurkatcher/google-maps-mcp","last_synced_at":"2026-05-04T08:01:55.093Z","repository":{"id":350856937,"uuid":"1208462855","full_name":"arthurkatcher/google-maps-mcp","owner":"arthurkatcher","description":"MCP server for Google Maps — places search, directions, geocoding. Works with Claude Desktop, Cursor, Claude Code. Install with uvx gmaps-mcp.","archived":false,"fork":false,"pushed_at":"2026-05-03T10:15:10.000Z","size":105,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-03T12:05:42.504Z","etag":null,"topics":["claude","claude-code","claude-desktop","cursor","fastmcp","google-maps","google-maps-api","google-places-api","mcp","mcp-server","model-context-protocol","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/gmaps-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arthurkatcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T10:13:16.000Z","updated_at":"2026-05-03T10:00:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arthurkatcher/google-maps-mcp","commit_stats":null,"previous_names":["arthurkatcher/google-maps-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arthurkatcher/google-maps-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurkatcher%2Fgoogle-maps-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurkatcher%2Fgoogle-maps-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurkatcher%2Fgoogle-maps-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurkatcher%2Fgoogle-maps-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arthurkatcher","download_url":"https://codeload.github.com/arthurkatcher/google-maps-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurkatcher%2Fgoogle-maps-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32599415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","claude-desktop","cursor","fastmcp","google-maps","google-maps-api","google-places-api","mcp","mcp-server","model-context-protocol","python"],"created_at":"2026-05-04T08:01:52.350Z","updated_at":"2026-05-04T08:01:55.082Z","avatar_url":"https://github.com/arthurkatcher.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"Google Maps MCP — red map pin with MCP badge\" width=\"160\"/\u003e\n\u003c/p\u003e\n\n# Google Maps MCP Server\n\n[![PyPI version](https://img.shields.io/pypi/v/gmaps-mcp.svg)](https://pypi.org/project/gmaps-mcp/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io)\n\n`gmaps-mcp` is an **MCP server that gives Claude Desktop, Cursor, and Claude Code full Google Maps capabilities** — places search, place details, nearby search, directions, geocoding, and reverse geocoding. Install with one line (`uvx gmaps-mcp`), drop a config block into your MCP client, and your AI assistant can talk to Google Maps natively.\n\nBuilt on the official [Model Context Protocol](https://modelcontextprotocol.io) Python SDK with FastMCP. Supports both **stdio transport** (local Claude Desktop / Cursor usage) and **streamable HTTP transport** (for remote deployments and A2A agent-to-agent scenarios).\n\n\u003c!-- TODO: record 15-second demo GIF of Claude Desktop using search_places and drop it here --\u003e\n\n## What you can ask Claude once it's installed\n\n- \"Find specialty coffee shops near me in San Francisco\"\n- \"What are the best ramen places in Shibuya, Tokyo, with reviews?\"\n- \"How long does it take to walk from Union Square to the Ferry Building?\"\n- \"Give me driving directions from SFO to Berkeley\"\n- \"What are the coordinates of the Eiffel Tower?\"\n- \"What's the address at 37.8199, -122.4783?\"\n- \"Find a 24-hour pharmacy within 2 km of these coordinates\"\n- \"Show me the top-rated Italian restaurants in North Beach with their hours and phone numbers\"\n\nThe MCP client picks the right tool automatically — you don't name it.\n\n## Install in Claude Desktop\n\nEdit your `claude_desktop_config.json` (Settings → Developer → Edit Config) and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-maps\": {\n      \"command\": \"uvx\",\n      \"args\": [\"gmaps-mcp\"],\n      \"env\": {\n        \"GOOGLE_MAPS_API_KEY\": \"your_google_maps_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. `uvx` fetches `gmaps-mcp` from PyPI on first run and caches it — no cloning, no venv, no Docker.\n\n## Install in Cursor\n\nEdit `~/.cursor/mcp.json` and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-maps\": {\n      \"command\": \"uvx\",\n      \"args\": [\"gmaps-mcp\"],\n      \"env\": {\n        \"GOOGLE_MAPS_API_KEY\": \"your_google_maps_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor. Done.\n\n## Install in Claude Code\n\nOne command from your terminal:\n\n```bash\nclaude mcp add google-maps \\\n  -e GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here \\\n  -- uvx gmaps-mcp\n```\n\nConfirm with `claude mcp list`.\n\n## Get a Google Maps API key\n\nYou need a Google Maps Platform API key with **Places API (New)**, **Directions API**, and **Geocoding API** enabled. It takes 3 minutes. Google gives **$200/month in free Maps credit**, far more than solo or small-team use will ever consume.\n\n### Step-by-step\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create (or pick) a project.\n2. **Enable billing** on the project. This is required even for the free tier. If you skip this step, every Google Maps call will return `403 BILLING_DISABLED` (see [Troubleshooting](#troubleshooting)). Add a card — the free credit runs first, so you will not be charged for normal use.\n3. Enable these APIs in **APIs \u0026 Services → Library**:\n   - **Places API (New)** — powers `search_places`, `get_place_details`, `search_nearby`\n   - **Directions API** — powers `get_directions`\n   - **Geocoding API** — powers `geocode`, `reverse_geocode`\n4. Go to **APIs \u0026 Services → Credentials → + CREATE CREDENTIALS → API key**.\n5. (Recommended) Click the new key → **Edit** → **API restrictions** → restrict to just those three APIs.\n6. Copy the key into your MCP client config above.\n\n## Tools\n\nAll six tools are real Google Maps calls against live data. No mocks, no stub responses.\n\n| Tool | What it does |\n|---|---|\n| [`search_places`](#search_places) | Text search for businesses, landmarks, POIs |\n| [`get_place_details`](#get_place_details) | Reviews, amenities, hours, phone, price level for a specific place |\n| [`search_nearby`](#search_nearby) | Find places within a radius of GPS coordinates, filtered by type |\n| [`get_directions`](#get_directions) | Step-by-step routes — driving, walking, bicycling, transit |\n| [`geocode`](#geocode) | Address or landmark → GPS coordinates |\n| [`reverse_geocode`](#reverse_geocode) | GPS coordinates → human-readable address |\n\n### `search_places`\n\nText search for places by natural-language query. Returns businesses, landmarks, and points of interest with ratings, addresses, phone numbers, websites, opening hours, and coordinates.\n\n**Ask Claude:**\n- \"find specialty coffee shops in San Francisco\"\n- \"best ramen in Shibuya\"\n- \"24-hour pharmacies in Brooklyn\"\n- \"pet-friendly cafes near Golden Gate Park\"\n\n**Returns:** `query`, `total_results`, `places[]` with `name`, `address`, `phone`, `website`, `google_maps_url`, `rating`, `reviews_count`, `price_level`, `types`, `latitude`, `longitude`, `is_open_now`, `opening_hours`, `business_status`.\n\n### `get_place_details`\n\nGet rich details about a specific place using its Google Place ID (returned by `search_places`). Includes reviews, amenities, editorial summary, and payment options.\n\n**Ask Claude:**\n- \"show me the reviews for that first coffee shop\"\n- \"is the second restaurant dog-friendly? do they have outdoor seating?\"\n- \"what are the opening hours and phone number of the place I just asked about\"\n\n**Returns:** everything from `search_places` plus top 5 `reviews` (author, rating, text, relative time), `editorial_summary`, and amenity flags: `delivery`, `dine_in`, `takeout`, `reservable`, `outdoor_seating`, `live_music`, `payment_options`, `accessibility_options`.\n\n### `search_nearby`\n\nFind places within a radius of specific GPS coordinates. Use after `geocode` gives you a location, or when the user provides coordinates directly.\n\n**Ask Claude:**\n- \"find cafes within 500 meters of these coordinates\"\n- \"what hotels are within 2 km of the Eiffel Tower?\"\n- \"show me gas stations within 5 km of 37.7955, -122.3937\"\n\n**Parameters:** `latitude`, `longitude`, `radius_meters` (max 50,000), `place_type` (optional — `restaurant`, `cafe`, `bar`, `hotel`, `gas_station`, `pharmacy`, `hospital`, etc.), `max_results`.\n\n**Returns:** `center`, `radius_meters`, `place_type`, `total_results`, `places[]` with the same fields as `search_places`.\n\n### `get_directions`\n\nStep-by-step navigation between two locations, with total distance and duration. Supports driving (with traffic-aware duration), walking, bicycling, and public transit.\n\n**Ask Claude:**\n- \"how do I walk from Union Square to the Ferry Building?\"\n- \"give me driving directions from SFO to Berkeley with traffic\"\n- \"bicycle route from Central Park to Times Square\"\n\n**Parameters:** `origin` (address, landmark, or `\"lat,lng\"`), `destination` (same), `mode` (`\"driving\"` default, `\"walking\"`, `\"bicycling\"`, `\"transit\"`).\n\n**Returns:** `origin`, `destination`, `mode`, `routes[]` with `summary`, `legs[]` containing `start_address`, `end_address`, `distance`, `duration`, `duration_in_traffic`, and `steps[]` with step-by-step `instruction`, `distance`, `duration`.\n\n### `geocode`\n\nConvert an address, landmark, or place description into GPS coordinates.\n\n**Ask Claude:**\n- \"what are the coordinates of the Eiffel Tower?\"\n- \"geocode 1600 Amphitheatre Parkway, Mountain View\"\n- \"find the latitude and longitude of Ferry Building San Francisco\"\n\n**Returns:** `query`, `formatted_address`, `latitude`, `longitude`, `place_id`, `location_type`, `types`.\n\n### `reverse_geocode`\n\nConvert GPS coordinates into a human-readable address.\n\n**Ask Claude:**\n- \"what's at 37.8199, -122.4783?\"\n- \"reverse geocode these coordinates: 48.8584, 2.2945\"\n- \"what address is at latitude 40.7580, longitude -73.9855?\"\n\n**Returns:** `latitude`, `longitude`, `formatted_address`, `place_id`, `address_components[]`.\n\n## Troubleshooting\n\n### `403 BILLING_DISABLED` / `403 Forbidden` from Google\n\nThis is the most common setup issue. The error looks like:\n\n```\nGoogle Maps API error: 403 - {\n  \"error\": {\n    \"code\": 403,\n    \"message\": \"This API method requires billing to be enabled...\",\n    \"status\": \"PERMISSION_DENIED\",\n    \"details\": [{\"reason\": \"BILLING_DISABLED\", ...}]\n  }\n}\n```\n\n**Fix:** Go back to [step 2 of the API key setup](#get-a-google-maps-api-key) and enable billing on your GCP project. Billing is required even though you will never actually be charged for normal solo use (Google's $200/month free credit handles it). **Wait 2-3 minutes** after enabling for the change to propagate through Google's systems, then retry.\n\n### `API_KEY_INVALID` / `API project not authorized`\n\nYou enabled billing but forgot to enable the specific APIs. Go back to [step 3](#get-a-google-maps-api-key) and turn on Places API (New), Directions API, and Geocoding API individually.\n\n### `uvx: command not found`\n\nInstall [`uv`](https://docs.astral.sh/uv/) first: `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"` (Windows).\n\n### Tools work in HTTP mode but not stdio (or vice versa)\n\nBoth transports share the exact same client and tool implementations — if one works, the other should too. If you hit a mismatch, open an issue with the error output.\n\n## Why this MCP server\n\nIf you're searching PyPI for a Google Maps MCP server, you'll find a couple of options. Here's what's different about `gmaps-mcp`:\n\n- **Both transports in one package.** Stdio for Claude Desktop / Cursor / Claude Code local usage, streamable HTTP for remote deployment and A2A scenarios. Same codebase, same tools, same behavior.\n- **All six Google Maps capabilities.** Not just search — places details, nearby search, directions with traffic, geocoding, reverse geocoding.\n- **Uses Places API (New).** The current Google Places API, not the legacy v1 endpoints that Google has deprecated.\n- **Real FastMCP implementation.** Built on the official MCP Python SDK, not a hand-rolled protocol parser.\n- **MIT licensed, zero telemetry.** Your queries never leave your machine except to hit Google's APIs directly.\n- **Tested against the real API.** Every tool is verified end-to-end against live Google endpoints on both transports.\n\n## Remote HTTP server mode\n\nFor deployments, shared team usage, or A2A agent-to-agent scenarios, `gmaps-mcp` also runs as a streamable HTTP server with optional API key auth.\n\n```bash\ngit clone https://github.com/arthurkatcher/google-maps-mcp\ncd google-maps-mcp\nuv sync\ncp .env.example .env  # edit with your API key\npython run.py\n```\n\nServer listens on `http://127.0.0.1:8000` by default, MCP endpoint at `/mcp/`, health check at `/health`. For local-only use you can leave `MCP_API_KEY` unset.\n\n\u003e ⚠️  **Before exposing the server publicly** (ngrok, reverse proxy, LAN, etc.):\n\u003e set `MCP_API_KEY` to a random secret. Without it, anyone who reaches the URL\n\u003e can run searches against your billed `GOOGLE_MAPS_API_KEY`. Also bind to\n\u003e `127.0.0.1` and let your tunnel/proxy forward from there, rather than\n\u003e binding `0.0.0.0` directly.\n\n```bash\n# .env\nMCP_API_KEY=$(openssl rand -hex 32)\nMCP_HOST=127.0.0.1\n\n# then\npython run.py\nngrok http 8000\n# clients call https://your-ngrok-url.ngrok-free.dev/mcp/ with X-API-Key: \u003csecret\u003e\n```\n\n## Pricing\n\nGoogle's Maps Platform offers a **$200/month free credit** that covers roughly:\n\n- ~11,000 Places API (New) requests, or\n- ~40,000 Geocoding API requests, or\n- ~40,000 Directions API requests.\n\nFor solo or small-team use, you will almost never hit the cap. Past the free tier, expect approximately $17 per 1,000 Places requests and $5 per 1,000 Geocoding/Directions requests. See [Google Maps Platform pricing](https://developers.google.com/maps/billing-and-pricing/pricing) for current rates.\n\n## Development\n\n```bash\ngit clone https://github.com/arthurkatcher/google-maps-mcp\ncd google-maps-mcp\nuv sync\ncp .env.example .env  # add your real API key\n\n# Run in stdio mode (for local MCP clients)\nuv run python -m google_maps_mcp\n\n# Run in HTTP mode (for remote clients)\nuv run python run.py\n```\n\n## Roadmap\n\n- **Places API v2 fields** — exploiting newer review/media fields as Google rolls them out\n- **Traffic-aware ETA tool** — dedicated tool for real-time travel time with traffic\n- **Place photos** — tool to fetch `PlacePhoto` URLs for UI rendering\n- **Static maps rendering** — optional tool to return a static map image for a place or route\n- **Autocomplete suggestions** — for building typeahead UX on top of the MCP server\n- **MCP registry submission** — listing on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) once it stabilizes\n\n## Project structure\n\n```\ngoogle-maps-mcp/\n├── pyproject.toml\n├── README.md\n├── LICENSE\n├── run.py                    # HTTP server entry point\n└── src/google_maps_mcp/\n    ├── __init__.py\n    ├── __main__.py           # stdio server entry point\n    ├── client.py             # Google Maps API client\n    ├── tools.py              # Tool wrappers\n    └── server.py             # FastMCP server + Starlette HTTP middleware\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE). Use it anywhere, fork it, ship it.\n\n## Credits\n\nBuilt by [Arthur Katcher](https://github.com/arthurkatcher). Contributions, bug reports, and PRs welcome at [github.com/arthurkatcher/google-maps-mcp](https://github.com/arthurkatcher/google-maps-mcp).\n\nIf this MCP server saves you time, a GitHub star is the only payment I ask for.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurkatcher%2Fgoogle-maps-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurkatcher%2Fgoogle-maps-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurkatcher%2Fgoogle-maps-mcp/lists"}