Claude Code

\n\n```bash\nclaude mcp add --transport http google-maps \"https://mcp.hasdata.com/api/mcp?apis=google_maps\" \\\n --header \"x-api-key: HASDATA_API_KEY\"\n```\n\n

\n\n

Claude Desktop

\n\nClaude Desktop loads only local (stdio) servers from its config file, so it reaches a remote server through a stdio launcher. The `@hasdata/google-maps-mcp` package is that launcher, and it reads the key from the environment.\n\n`claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hasdata/google-maps-mcp\"],\n \"env\": { \"HASDATA_API_KEY\": \"YOUR_KEY\" }\n }\n }\n}\n```\n\nPython instead of Node? Swap the launcher for the PyPI package, which `uvx` runs without a manual install:\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"command\": \"uvx\",\n \"args\": [\"hasdata-google-maps-mcp\"],\n \"env\": { \"HASDATA_API_KEY\": \"YOUR_KEY\" }\n }\n }\n}\n```\n\nA client with OAuth support can instead add the URL as a custom connector and skip the launcher.\n\n

\n\n

Cursor

\n\n`.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"url\": \"https://mcp.hasdata.com/api/mcp?apis=google_maps\",\n \"headers\": { \"x-api-key\": \"HASDATA_API_KEY\" }\n }\n }\n}\n```\n\n

\n\n

Windsurf

\n\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"serverUrl\": \"https://mcp.hasdata.com/api/mcp?apis=google_maps\",\n \"headers\": { \"x-api-key\": \"HASDATA_API_KEY\" }\n }\n }\n}\n```\n\n

\n\n

Cline

\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"url\": \"https://mcp.hasdata.com/api/mcp?apis=google_maps\",\n \"type\": \"streamableHttp\",\n \"headers\": { \"x-api-key\": \"HASDATA_API_KEY\" },\n \"disabled\": false\n }\n }\n}\n```\n\n

\n\n

VS Code

\n\n`.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"google-maps\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.hasdata.com/api/mcp?apis=google_maps\",\n \"headers\": { \"x-api-key\": \"HASDATA_API_KEY\" }\n }\n }\n}\n```\n\n

\n\n

Gemini CLI

\n\n`~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"google-maps\": {\n \"httpUrl\": \"https://mcp.hasdata.com/api/mcp?apis=google_maps\",\n \"headers\": { \"x-api-key\": \"HASDATA_API_KEY\" }\n }\n }\n}\n```\n\n

\n\n## Example prompts\n\nEach of these is one tool call unless the count says otherwise.\n\n> Search Google Maps for coffee near downtown Seattle and give me the top ten with their rating, review count and website.\n\n*One call, 5 credits. Search returns the places with `placeId` and `dataId` already attached, and the follow-ups below need no lookup step.*\n\n> Pull the full details for `ChIJAb0KE0RrkFQRuI4X0By5Mcw`: hours, service options, price level and the menu link.\n\n*One call, 5 credits.*\n\n> Read the latest reviews for that place, sorted newest first, and tell me which topics come up most.\n\n*One call, 5 credits. The response carries Google's own topic clusters with a mention count each, and the ranking is in the data.*\n\n> Take the author of the top review and list every other place they have reviewed, with the rating they left.\n\n*One call, 5 credits. A review carries its author's `contributorId`, which is exactly what the contributor tool takes.*\n\n> Get the photo feed for that place and the business's recent posts.\n\n*Two calls. Photos cost 5 credits, posts cost 10.*\n\nTwo things make these chains cheap. Search hands back `placeId` and `dataId` on every result, and the detail, review, photo and post calls need no separate resolve step. And a review carries the author's `contributorId`, which turns \"who left this review\" into a one-call jump to that person's whole history.\n\n## Tools\n\nSix tools, all read-only. Samples below are trimmed from real calls, and the numbers in them move as places gain reviews. Read them as shapes. Each tool name links to its endpoint reference.\n\nThe samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.\n\nFour of the tools accept a place by either `placeId` or `dataId`. Search returns both on every result. The usual flow is one search followed by detail, review, photo or post calls that reuse whichever id you kept.\n\n### Search Google Maps\n\n[`hasdata_google_maps_search_performMapSearch`](https://docs.hasdata.com/apis/google-maps/search?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nPlaces for a query, ranked as Google Maps ranks them.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `q` | string | yes | Free-text query, for example `coffee` or `plumber` |\n| `ll` | string | | Map centre and zoom as `@lat,lng,zoomz`, for example `@47.6062,-122.3321,14z`. This is how you pin the search to a place |\n| `gl` / `hl` | string | | Two-letter country and language codes |\n| `domain` | string | | Google domain to query, for example `google.com` |\n| `start` | number | | Result offset for paging, in steps of 20. Requires `ll` to be set as well |\n\nEach result carries `position`, `title`, `placeId`, `dataId`, `address`, `gpsCoordinates`, `rating`, `reviews`, `type`, `types`, `price`, `website`, `thumbnail`, `openState`, `workingHours`, `serviceOptions` and, where Google shows one, a `menu` link.\n\n> Location lives in `ll`, not in the query. Put the map centre and zoom there, because \"coffee\" alone returns wherever Google decides you are. The zoom digit widens or narrows the area the results are drawn from.\n\n```json\n{\n \"localResults\": [\n {\n \"position\": 1,\n \"title\": \"Howdy Y'all Coffee (Central Library)\",\n \"placeId\": \"ChIJAb0KE0RrkFQRuI4X0By5Mcw\",\n \"dataId\": \"0x54906b44130abd01:0xcc31b91cd0178eb8\",\n \"address\": \"1000 4th Ave Fl 3, Seattle, WA 98104\",\n \"rating\": 4.9,\n \"reviews\": 117,\n \"type\": \"Coffee shop\",\n \"website\": \"https://howdyyallcoffee.com/\",\n \"workingHours\": {\n \"timezone\": \"America/Los_Angeles\",\n \"days\": [ { \"day\": \"Friday\", \"time\": \"10 AM–4 PM\" } ]\n }\n }\n ]\n}\n```\n\n### Get place details\n\n[`hasdata_google_maps_place_getPlaceDetails`](https://docs.hasdata.com/apis/google-maps/place?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nOne place in full by `placeId`.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `placeId` | string | yes | The `placeId` from a search result |\n| `hl` | string | | Language code |\n| `domain` | string | | Google domain |\n\nReturns a single `placeResults` object with the same fields a search result carries, plus an `images` array. It is the way to get one place's full record without running a search you do not need.\n\n### Get place reviews\n\n[`hasdata_google_maps_reviews_getMapReviews`](https://docs.hasdata.com/apis/google-maps/reviews?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nThe review feed for a place, page by page.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `placeId` | string | | The place. Either `placeId` or `dataId` has to be present |\n| `dataId` | string | | The place as a `dataId` instead |\n| `sortBy` | string | | `mostRelevant` by default, plus `newestFirst`, `ratingHigh` and `ratingLow` |\n| `topicId` | string | | Filter to one topic, using an `id` from the `topics` array |\n| `hl` | string | | Language code |\n| `nextPageToken` | string | | The `pagination.nextPageToken` from the previous response |\n\nReturns `placeInfo`, a `topics` array, a `reviews` array and `pagination`. Each review carries `reviewId`, `rating`, `snippet`, `date`, `isoDate`, `link`, `images`, a `user` object and, where the owner replied, a `response`.\n\n> `topics` is Google's own clustering of what reviews mention, each with a `keyword` and a `mentions` count, and the themes come pre-counted rather than needing you to read every review. Feed a topic's `id` back as `topicId` to read only the reviews that mention it.\n\n> Each review's `user` carries a `contributorId`. That is the input the contributor tool takes, so \"who wrote this\" is one call away from \"everything they wrote\".\n\n```json\n{\n \"placeInfo\": { \"title\": \"Howdy Y'all Coffee (Central Library)\", \"rating\": 4.9, \"reviews\": 117 },\n \"topics\": [\n { \"keyword\": \"earl grey matcha\", \"mentions\": 26, \"id\": \"bew1w_KAk5U\" },\n { \"keyword\": \"friendly baristas\", \"mentions\": 17, \"id\": \"FOw-91tYieQ\" }\n ],\n \"reviews\": [\n {\n \"reviewId\": \"…\",\n \"rating\": 5,\n \"snippet\": \"…\",\n \"isoDate\": \"2026-07-06T19:49:00.657Z\",\n \"user\": { \"name\": \"Angela Li\", \"contributorId\": \"106033685843245983748\" },\n \"response\": { \"isoDate\": \"2026-07-07T04:44:34.000Z\", \"snippet\": \"Thank you!! 🥺☺️\" }\n }\n ],\n \"pagination\": { \"nextPageToken\": \"…\" }\n}\n```\n\n### Get a contributor's reviews\n\n[`hasdata_google_maps_contributor_reviews_getMapReviews`](https://docs.hasdata.com/apis/google-maps/contributor-reviews?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nEvery review one person has written, across all the places they rated.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `contributorId` | string | yes | The `contributorId` from a review's `user` object |\n| `num` | number | | How many reviews to return |\n| `gl` / `hl` | string | | Country and language codes |\n| `nextPageToken` | string | | Token from the previous response |\n\nReturns a `contributor` object with `name`, `level`, `points` and a `contributions` breakdown, and a `reviews` array where every entry carries its own `placeInfo`, and you see which place each review is about without a second lookup. This is the tool behind reviewer-credibility and review-network work that the review feed alone cannot do. It reads one person's public review history, so use the results within Google's terms and the law that applies to you.\n\n### Get place photos\n\n[`hasdata_google_maps_photos_getMapPhotos`](https://docs.hasdata.com/apis/google-maps/photos?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nThe photo feed for a place.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `placeId` | string | | The place. Either `placeId` or `dataId` has to be present |\n| `dataId` | string | | The place as a `dataId` instead |\n| `categoryId` | string | | Filter to one category, using an `id` from the `categories` array |\n| `hl` | string | | Language code |\n| `nextPageToken` | string | | Token from the previous response |\n\nReturns a `categories` array (`All`, `Latest`, `Videos`, `Menu` and place-specific ones), a `photos` array where each entry has `image` and `thumbnail` URLs, and `pagination`.\n\n### Get place posts\n\n[`hasdata_google_maps_posts_getMapPosts`](https://docs.hasdata.com/apis/google-maps/posts?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)\n\nThe business's own posts and updates on its Google listing.\n\n| Parameter | Type | Required | Notes |\n| :--- | :--- | :--- | :--- |\n| `placeId` | string | | The place. Either `placeId` or `dataId` has to be present |\n| `dataId` | string | | The place as a `dataId` instead |\n| `hl` | string | | Language code |\n| `nextPageToken` | string | | Token from the previous response |\n\nReturns a `posts` array.\n\n> Most places post nothing, so an empty `posts` array is the common case. Read the length before assuming a post is there.\n\n## Errors and failure paths\n\nYour client almost never sees an HTTP error code from a tool call. The MCP layer answers 200 and puts the failure inside the result, with `isError` set to `true` and the reason as text. The agent reads a message where you might expect a status line.\n\n**A wrong key surfaces as tool output, not as a failed connection.** Listing tools accepts any non-empty key, and the client completes its handshake and shows green. The first tool call then comes back with `isError: true` and the text `HasData API error: 401 Unauthorized`. Watch for that string, because nothing earlier in the flow reports the problem.\n\nThe one real HTTP error is a **missing key**. Authorization runs before any tool, and the connection itself fails with 401.\n\n**An argument that breaks the schema is rejected before it becomes a request.** A search with no `q` comes back with `isError: true` and the text `MCP error -32602: Input validation error`, naming the field. Nothing is fetched and nothing is charged.\n\n**A review, photo or post call needs a place.** Those three take `placeId` or `dataId`, and sending neither returns 422 naming both fields, because the requirement is conditional and the schema cannot express it as a plain required list. Pass one.\n\n**A place id that does not resolve is a clean error, not empty data.** It returns `isError: true` with `HasData API error: 400 Bad Request` and `requestMetadata.status` set to `error`. Test the flag rather than the array length.\n\n**Empty `posts` is real data.** Most listings carry no posts, so the call succeeds with `status` `ok` and an empty array. The place simply has nothing posted.\n\nResults that carry data also carry a `requestMetadata.id` worth quoting in support, plus `html` and `json` links to the stored artifact of that exact call.\n\n## Pricing, free tier and limits\n\nSearch, place details, reviews, contributor reviews and photos cost **5 credits per successful call**. Posts cost **10**. Response size does not change the price. A full page of reviews costs the same as a page with one.\n\nThe free trial is **1,000 credits over 30 days with no card**, which is 200 calls at the 5-credit rate. After that an active account keeps getting 100 credits topped up each day whenever its balance drops below 100, so a low-volume agent runs on the free tier indefinitely.\n\nPaid plans start at **$49 a month** for 200,000 credits, which is 40,000 five-credit calls. The price per credit falls with volume, and current numbers live on the [pricing page](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp).\n\nYour plan also sets concurrency. The free trial allows 1 request at a time, Startup 15, Business 30, Growth 50, and the high-volume plans run from 200 to 1,500. Concurrency is the only throttle. There is no separate requests-per-minute cap, and the trial is not slowed or trimmed in any other way. Handle the overflow case defensively in anything unattended, because an agent that fans out across places will reach the ceiling before you do.\n\nPaging costs a call each time. Reviews come about ten to a page, so a hundred reviews is roughly ten calls and 50 credits, while photos come twenty to a page. The trial goes a long way before you feel it.\n\n## Tool selection\n\n`?apis=google_maps` exposes exactly these six tools. The parameter takes a list, and `?apis=google_maps,google_serp` adds Google search alongside the maps tools. Drop the parameter and you get everything HasData exposes, which is currently 57 tools.\n\nA narrow list is usually the better default. A model choosing among six tools picks correctly more often than one choosing among fifty-seven, and the tool descriptions themselves cost context on every turn.\n\n## How it compares\n\nAlmost every other Google Maps MCP server wraps the official Google Maps Platform, and that is the real choice to weigh.\n\nThose servers call the Places, Routes and Geocoding APIs with your own Google Cloud credentials. To run one you create a Google Cloud project, enable billing with a card, turn on each API, and manage a key and its quotas. That is the right tool when you want routing, geocoding and address validation, which this server does not do.\n\nThis server reads what Google Maps shows a visitor, and returns it parsed. There is no Google Cloud project, no billing to enable, and no per-API quota to manage. It also reaches data the Places API does not hand out: the full review feed rather than a small fixed sample, a single reviewer's whole history, the photo feed, and the business's posts.\n\n| | Official Platform wrapper | This server |\n| :--- | :--- | :--- |\n| What you set up | A Google Cloud project, billing, per-API keys and quotas | One API key, once |\n| Routing, geocoding, address validation | Yes | Not offered |\n| Reviews | A small fixed sample per place | The feed, paged, with topic clusters |\n| A reviewer's history | Not available | Yes, by `contributorId` |\n| Photos and posts | Limited | Photo feed and the business's posts |\n| Output | JSON per the Platform schema | JSON parsed from what a visitor sees |\n| Cost | Google's per-call pricing on your bill | 5 credits a call, 10 for posts |\n\nThe decision comes down to two rows. If you need directions or to turn an address into coordinates, this server cannot help you and the Platform can. If you need the reviews behind the first few, or who a reviewer is across every place they rated, the Platform cannot help you and this can.\n\n**What this server does not do.** No routing, no geocoding, no address validation, no distance matrix, and nothing that writes. It reads the map.\n\n## FAQ\n\n### What is a Google Maps MCP server?\n\nA server that exposes Google Maps data as tools an AI client can call. The client sends a tool call over the Model Context Protocol, the server fetches the data and returns structured JSON, and the model works with the result and never sees a page of HTML. This one exposes six read-only tools and runs remotely. The client connects to a URL and starts no local process.\n\n### Is there an official Google Maps MCP server?\n\nGoogle publishes no general-purpose one. There is the Google Maps Platform, a set of paid APIs you call with your own Cloud project, and several community MCP servers wrap it. This server is a hosted alternative that needs no Cloud project.\n\n### Do I need a Google Cloud project or a Maps API key?\n\nNo. The only credential is your HasData key. There is no Google Cloud project to create, no billing to enable and no per-API quota to manage.\n\n### What is the difference between `placeId` and `dataId`?\n\nThey are two ids Google uses for the same place. Search returns both on every result, and the detail, review, photo and post tools accept either. Keep whichever you like from the search result and reuse it.\n\n### How do I get every review, not just the first page?\n\nRead `pagination.nextPageToken` from each response and pass it back as `nextPageToken` until it stops coming. Each page is one call.\n\n### Do I need to host or run anything?\n\nNo. This is a remote MCP server on streamable HTTP. Nothing to install, no Python environment, no process to restart.\n\n### Is the data live or cached?\n\nLive. Each call fetches at request time and carries its own `requestMetadata.id`. Two identical calls are two separate fetches and not a replay of a stored copy.\n\n### Can I use one server for several Google surfaces?\n\nYes. The `apis` parameter takes a list, and `?apis=google_maps,google_serp` gives your agent the maps tools plus Google search at once.\n\n### Does the API key expire?\n\nNo. The key does not expire. Rotate it in the dashboard whenever you need to.\n\n### Is this affiliated with Google?\n\nNo. HasData is an independent service and is not affiliated with, endorsed by, or sponsored by Google. Google and Google Maps are trademarks of their respective owner. The tools work with publicly available data only, and you are responsible for using the results in line with Google's terms and the law that applies to you.\n\n## HasData links\n\n| | |\n| :--- | :--- |\n| Product pages | [Search](https://hasdata.com/apis/google-maps-search-api?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp), [Reviews](https://hasdata.com/apis/google-maps-reviews-api?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp), [Photos](https://hasdata.com/apis/google-maps-photos-api?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) and [Posts](https://hasdata.com/apis/google-maps-posts-api?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| Server documentation | [MCP server docs](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| All 57 tools in one server | [HasData/hasdata-mcp](https://github.com/HasData/hasdata-mcp) |\n| Client walkthroughs | [MCP clients and integrations](https://hasdata.com/integrations/mcp?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| The other surfaces we parse | [53 more scraper APIs](https://hasdata.com/apis/?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| Plans and credit costs | [Plans and credit costs](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| Keys and usage | [HasData dashboard](https://app.hasdata.com?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp) |\n| Node launcher on npm | [@hasdata/google-maps-mcp](https://www.npmjs.com/package/@hasdata/google-maps-mcp) |\n| Python launcher on PyPI | [hasdata-google-maps-mcp](https://pypi.org/project/hasdata-google-maps-mcp/) |\n\n## Development\n\nThis repository is configuration and documentation for a remote server. There is no build step and nothing to containerize.\n\nIt does carry a contract test. The README promises six tools with specific parameters, and the upstream tool list can change without a commit here, which would leave this file quietly lying to you. The test asserts the promise and runs weekly in CI as well as on every push.\n\n```bash\nHASDATA_API_KEY=your_key_here npm test\n```\n\nOn PowerShell:\n\n```powershell\n$env:HASDATA_API_KEY = \"your_key_here\"; npm test\n```\n\nThe last check makes a real call and costs 5 credits, which is the price of a canary that can fail for the right reason. Listing tools succeeds with any non-empty key, and a test that only lists tools stays green with a revoked one.\n\n## Contributing\n\nCorrections to the tool tables and the response samples are the most useful contribution, because those are the parts that drift. Include the call you made and the response you got. Pull requests from forks run the suite without a key, and the live checks skip instead of going red.\n\n## License\n\nMIT. See [LICENSE](https://github.com/HasData/google-maps-mcp/blob/main/LICENSE).\n","changelogMarkdown","videoKey","requiredSecretsJson","[{\"name\":\"x-api-key\",\"scope\":\"per-user\",\"header\":\"x-api-key\"}]","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_119":120,"_121":122,"_123":124,"_125":126,"_127":128,"_129":130},"requiredSecrets",[113],"tags",[101,102,103,104,19,105,106,107,108,109,110,111,112],"assets",[],"stats",{"_99":86,"_100":86},"ratingAvg","reviewCount","ai-agents","claude","cursor","google-maps","llm-tools","local-seo","location","maps","places","reviews","web-scraping","windsurf",{"_114":115,"_116":117,"_118":115},"name","x-api-key","scope","per-user","header","topics",[101,102,103,104,19,105,106,107,108,139,140,141,109,110,111,112],"license","MIT","language","JavaScript","registryName","com.hasdata/google-maps","homepage","https://hasdata.com/apis/google-maps-search-api","packages",[131,132],{"_133":138,"_135":22,"_75":137},{"_133":134,"_135":136,"_75":137},"registryType","pypi","identifier","hasdata-google-maps-mcp","1.0.2","npm","mcp","mcp-server","model-context-protocol","ENV",{"_144":145,"_146":147,"_148":149},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

HasData Google Maps