google-maps-mcp

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

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

[![tool contract](https://github.com/HasData/google-maps-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/google-maps-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-6-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp), free to create with no card, and the trial covers about 200 calls at the 5-credit rate. Nothing else. This is a remote server. There is no package to install, no container to run, and no Google Cloud project or API key anywhere in the flow.

## Quick start

| | |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/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.

<details>
<summary><b>Claude Code</b></summary>

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

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Claude Desktop loads only local (stdio) servers from its config file, so a remote server is reached through the `mcp-remote` bridge. Node has to be on the machine.

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hasdata.com/api/mcp?apis=google_maps",
        "--header",
        "x-api-key:HASDATA_API_KEY"
      ]
    }
  }
}
```

The `x-api-key:` value carries no space after the colon. Claude Desktop passes the argument without a shell, and a space splits the header. A client with OAuth support can instead add the URL as a custom connector and skip the bridge.

</details>

<details>
<summary><b>Cursor</b></summary>

`.cursor/mcp.json`:

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

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`:

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

</details>

<details>
<summary><b>Cline</b></summary>

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

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json`:

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

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

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

</details>

## 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`](https://docs.hasdata.com/apis/google-maps/search?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)

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.

```json
{
  "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`](https://docs.hasdata.com/apis/google-maps/place?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)

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`](https://docs.hasdata.com/apis/google-maps/reviews?utm_source=github&utm_medium=syndication&utm_campaign=google-maps-mcp)

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 `pag