HasData Google Maps README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the HasData Google Maps listing page.
Google Maps MCP Server
A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client six read-only Google Maps tools. Search places, read a place in full, pull its reviews, photos and posts, and walk a single reviewer's history, all as structured JSON, with no Google Cloud project and no billing to enable.
1,000 free credits every month, no card required, which is 200 calls at the 5-credit rate.
Contents
- What you need
- Quick start
- Example prompts
- Tools
- Errors and failure paths
- Pricing, free tier and limits
- Tool selection
- How it compares
- FAQ
- HasData links
- Development
- Contributing
- License
What you need
An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the dashboard, free to create with no card, and the free tier covers about 200 calls a month at the 5-credit rate. Nothing else. This is a remote server, so the simplest path is a URL and a header, with no container to run and no Google Cloud project or API key anywhere in the flow. A stdio-only client can use the @hasdata/google-maps-mcp (npm) or hasdata-google-maps-mcp (PyPI) launcher instead.
Quick start
| URL | https://mcp.hasdata.com/mcp?apis=google_maps |
| Transport | HTTP, streamable |
| Auth header | x-api-key: HASDATA_API_KEY |
The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.
Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.
Claude Code
Claude Desktop
Claude 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.
claude_desktop_config.json:
Python instead of Node? Swap the launcher for the PyPI package, which uvx runs without a manual install:
A client with OAuth support can instead add the URL as a custom connector and skip the launcher.
Cursor
.cursor/mcp.json:
Windsurf
~/.codeium/windsurf/mcp_config.json:
Cline
VS Code
.vscode/mcp.json:
Gemini CLI
~/.gemini/settings.json:
Example prompts
Each of these is one tool call unless the count says otherwise.
Search Google Maps for coffee near downtown Seattle and give me the top ten with their rating, review count and website.
One call, 10 credits. Search returns the places with placeId and dataId already attached, and the follow-ups below need no lookup step.
Pull the full details for
ChIJAb0KE0RrkFQRuI4X0By5Mcw: hours, service options, price level and the menu link.
One call, 10 credits.
Read the latest reviews for that place, sorted newest first, and tell me which topics come up most.
One call, 10 credits. The response carries Google's own topic clusters with a mention count each, and the ranking is in the data.
Take the author of the top review and list every other place they have reviewed, with the rating they left.
One call, 10 credits. A review carries its author's contributorId, which is exactly what the contributor tool takes.
Get the photo feed for that place and the business's recent posts.
Two calls. Photos and posts cost 10 credits each.
Two 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.
Tools
| Tool | What it returns |
|---|---|
hasdata_google_maps_contributor_reviews_getMapReviews | Per-review rating, text, date, place name, place address, placeId, photos, and owner responses. 10 credits a call |
hasdata_google_maps_photos_getMapPhotos | Each photo with image URL, thumbnail, upload date, uploader, and photoId. 10 credits a call |
hasdata_google_maps_place_getPlaceDetails | Name, address, coordinates, phone, website, categories, hours, rating, review count, price level, photos, popular times, attributes/amenities, plus_code, and map URL. 10 credits a call |
hasdata_google_maps_posts_getMapPosts | Per-post title, description, image, posted_at, link, and source/business name. 10 credits a call |
hasdata_google_maps_reviews_getMapReviews | Per-review author name and profile link, star rating, text, published/relative date, likes count, owner response, attached photos, and local-guide flag. 10 credits a call |
hasdata_google_maps_search_performMapSearch | The local pack list with placeId, name, address, coordinates, rating, review count, price level, categories, phone, website, hours, and thumbnail. 10 credits a call |
Six 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.
The 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.
Four 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.
Search Google Maps
hasdata_google_maps_search_performMapSearch
Places for a query, ranked as Google Maps ranks them.
| Parameter | Type | Required | Notes |
|---|---|---|---|
q | string | yes | Free-text query, for example coffee or plumber |
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 | |
gl / hl | string | Two-letter country and language codes | |
domain | string | Google domain to query, for example google.com | |
start | number | Result offset for paging, in steps of 20. Requires ll to be set as well |
Each 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.
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.
Get place details
hasdata_google_maps_place_getPlaceDetails
One place in full by placeId.
| Parameter | Type | Required | Notes |
|---|---|---|---|
placeId | string | yes | The placeId from a search result |
hl | string | Language code | |
domain | string | Google domain |
Returns 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.
Get place reviews
hasdata_google_maps_reviews_getMapReviews
The review feed for a place, page by page.
| Parameter | Type | Required | Notes |
|---|---|---|---|
placeId | string | The place. Either placeId or dataId has to be present | |
dataId | string | The place as a dataId instead | |
sortBy | string | mostRelevant by default, plus newestFirst, ratingHigh and ratingLow | |
topicId | string | Filter to one topic, using an id from the topics array | |
hl | string | Language code | |
nextPageToken | string | The pagination.nextPageToken from the previous response |
Returns 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.
topicsis Google's own clustering of what reviews mention, each with akeywordand amentionscount, and the themes come pre-counted rather than needing you to read every review. Feed a topic'sidback astopicIdto read only the reviews that mention it.
Each review's
usercarries acontributorId. That is the input the contributor tool takes, so "who wrote this" is one call away from "everything they wrote".
Get a contributor's reviews
hasdata_google_maps_contributor_reviews_getMapReviews
Every review one person has written, across all the places they rated.
| Parameter | Type | Required | Notes |
|---|---|---|---|
contributorId | string | yes | The contributorId from a review's user object |
num | number | How many reviews to return | |
gl / hl | string | Country and language codes | |
nextPageToken | string | Token from the previous response |
Returns 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.
Get place photos
hasdata_google_maps_photos_getMapPhotos
The photo feed for a place.
| Parameter | Type | Required | Notes |
|---|---|---|---|
placeId | string | The place. Either placeId or dataId has to be present | |
dataId | string | The place as a dataId instead | |
categoryId | string | Filter to one category, using an id from the categories array | |
hl | string | Language code | |
nextPageToken | string | Token from the previous response |
Returns a categories array (All, Latest, Videos, Menu and place-specific ones), a photos array where each entry has image and thumbnail URLs, and pagination.
Get place posts
hasdata_google_maps_posts_getMapPosts
The business's own posts and updates on its Google listing.
| Parameter | Type | Required | Notes |
|---|---|---|---|
placeId | string | The place. Either placeId or dataId has to be present | |
dataId | string | The place as a dataId instead | |
hl | string | Language code |
Returns a posts array. This tool does not page. Reviews and photos take a nextPageToken, this one does not, and it returns what the listing shows.
Most places post nothing, so an empty
postsarray is the common case. Read the length before assuming a post is there.
Prompts and resources
The server ships 2 prompts, ready-made workflows a client can offer instead of making the user compose a tool call.
| Prompt | What it does |
|---|---|
google_maps_search | Find businesses and places on Google Maps. |
google_maps_reviews | Summarize what reviewers say about a place. |
Alongside them the server exposes 4 resources, one per parameter whose accepted values are a fixed list. Reading one is cheaper than learning the vocabulary from a rejected call, and it costs no credits. Each URI is hasdata://google_maps/<parameter>.
| Parameter | Values | What it selects |
|---|---|---|
hl | 159 | The two-letter language code for the language you want to use for the search. |
gl | 245 | The two-letter country code for the country you want to limit the search to. |
domain | 195 | Google domain to use. Default is google.com. |
sortBy | 4 | Parameter used for sorting and refining results. |
Both lists are served without an API key, so a client can read them before a user has signed up.
Errors and failure paths
Your 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.
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.
The one real HTTP error is a missing key. Authorization runs before any tool, and the connection itself fails with 401.
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.
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.
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.
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.
Results 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.
Pricing, free tier and limits
Search, place details, reviews, contributor reviews and photos cost 10 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.
The free tier is 1,000 credits every month with no card, which is 200 calls at the 5-credit rate. It renews with the billing cycle, so a low-volume agent runs on the free tier indefinitely.
Paid plans start at $59 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.
Your plan also sets concurrency. The free tier allows 1 request at a time, Startup 5, Basic 15, and the Growth tiers run from 50 to 500. Concurrency is the only throttle. There is no separate requests-per-minute cap, and the free tier 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.
Paging costs a call each time. Reviews come about ten to a page, so a hundred reviews is roughly ten calls and 100 credits, while photos come twenty to a page. The free tier goes a long way before you feel it.
Tool selection
?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.
A 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.
How it compares
Almost every other Google Maps MCP server wraps the official Google Maps Platform, and that is the real choice to weigh.
Those 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.
This 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.
| Official Platform wrapper | This server | |
|---|---|---|
| What you set up | A Google Cloud project, billing, per-API keys and quotas | One API key, once |
| Routing, geocoding, address validation | Yes | Not offered |
| Reviews | A small fixed sample per place | The feed, paged, with topic clusters |
| A reviewer's history | Not available | Yes, by contributorId |
| Photos and posts | Limited | Photo feed and the business's posts |
| Output | JSON per the Platform schema | JSON parsed from what a visitor sees |
| Cost | Google's per-call pricing on your bill | 10 credits a call, 10 for posts |
The 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.
What this server does not do. No routing, no geocoding, no address validation, no distance matrix, and nothing that writes. It reads the map.
FAQ
What is a Google Maps MCP server?
A 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.
Is there an official Google Maps MCP server?
Google 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.
Do I need a Google Cloud project or a Maps API key?
No. 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.
What is the difference between placeId and dataId?
They 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.
How do I get every review, not just the first page?
Read pagination.nextPageToken from each response and pass it back as nextPageToken until it stops coming. Each page is one call.
Do I need to host or run anything?
No. This is a remote MCP server on streamable HTTP. Nothing to install, no Python environment, no process to restart.
Is the data live or cached?
Live. 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.
Can I use one server for several Google surfaces?
Yes. The apis parameter takes a list, and ?apis=google_maps,google_serp gives your agent the maps tools plus Google search at once.
Does the API key expire?
No. The key does not expire. Rotate it in the dashboard whenever you need to.
Is this affiliated with Google?
No. 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.
HasData links
| Product pages | Search, Reviews, Photos and Posts |
| Server documentation | MCP server docs |
| All 57 tools in one server | HasData/hasdata-mcp |
| Client walkthroughs | MCP clients and integrations |
| The other surfaces we parse | 53 more scraper APIs |
| Plans and credit costs | Plans and credit costs |
| Keys and usage | HasData dashboard |
| Node launcher on npm | @hasdata/google-maps-mcp |
| Python launcher on PyPI | hasdata-google-maps-mcp |
Development
This repository is configuration and documentation for a remote server. There is no build step and nothing to containerize.
It 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.
On PowerShell:
The last check makes a real call and costs 10 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.
Contributing
Corrections 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.
License
MIT. See LICENSE.