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.

https://mcp.hasdata.com/mcp?apis=google_maps

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

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 mcp add --transport http google-maps "https://mcp.hasdata.com/mcp?apis=google_maps" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": ["hasdata-google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

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

{
  "mcpServers": {
    "google-maps": {
      "serverUrl": "https://mcp.hasdata.com/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

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

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

{
  "mcpServers": {
    "google-maps": {
      "httpUrl": "https://mcp.hasdata.com/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

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, 5 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, 5 credits.

Read the latest reviews for that place, sorted newest first, and tell me which topics come up most.

One call, 5 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, 5 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 cost 5 credits, posts cost 10.

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

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.

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.

{
  "localResults": [
    {
      "position": 1,
      "title": "Howdy Y'all Coffee (Central Library)",
      "placeId": "ChIJAb0KE0RrkFQRuI4X0By5Mcw",
      "dataId": "0x54906b44130abd01:0xcc31b91cd0178eb8",
      "address": "1000 4th Ave Fl 3, Seattle, WA 98104",
      "rating": 4.9,
      "reviews": 117,
      "type": "Coffee shop",
      "website": "https://howdyyallcoffee.com/",
      "workingHours": {
        "timezone": "America/Los_Angeles",
        "days": [ { "day": "Friday", "time": "10 AM–4 PM" } ]
      }
    }
  ]
}

Get place details

hasdata_google_maps_place_getPlaceDetails

One place in full by placeId.

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.

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.

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.

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".

{
  "placeInfo": { "title": "Howdy Y'all Coffee (Central Library)", "rating": 4.9, "reviews": 117 },
  "topics": [
    { "keyword": "earl grey matcha", "mentions": 26, "id": "bew1w_KAk5U" },
    { "keyword": "friendly baristas", "mentions": 17, "id": "FOw-91tYieQ" }
  ],
  "reviews": [
    {
      "reviewId": "…",
      "rating": 5,
      "snippet": "…",
      "isoDate": "2026-07-06T19:49:00.657Z",
      "user": { "name": "Angela Li", "contributorId": "106033685843245983748" },
      "response": { "isoDate": "2026-07-07T04:44:34.000Z", "snippet": "Thank you!! 🥺☺️" }
    }
  ],
  "pagination": { "nextPageToken": "…" }
}

Get a contributor's reviews

hasdata_google_maps_contributor_reviews_getMapReviews

Every review one person has written, across all the places they rated.

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.

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.

Returns a posts array.

Most places post nothing, so an empty posts array is the common case. Read the length before assuming a post is there.

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

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 50 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.

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

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.

HASDATA_API_KEY=your_key_here npm test

On PowerShell:

$env:HASDATA_API_KEY = "your_key_here"; npm test

The 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.

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.