> ## Documentation Index
> Fetch the complete documentation index at: https://gmapscrawl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect the MCP server

> Configure Streamable HTTP and make your first bounded tool call.

G Maps Crawl MCP is officially released and available on free and paid API plans. MCP requests use the same API allowance as REST requests. Online and Extension allowances are separate. Plan limits, credential permissions, and source availability still apply.

The hosted endpoint is:

```text theme={null}
https://gmapscrawl.com/api/mcp
```

Use a client that supports remote **Streamable HTTP** and custom authentication headers. This is the product data server; it is separate from any documentation-search MCP offered by Mintlify.

## Codex

Configure `GMSCRAPER_API_KEY` in the environment where Codex starts, then add the server:

```bash theme={null}
codex mcp add gmapscrawl \
  --url https://gmapscrawl.com/api/mcp \
  --bearer-token-env-var GMSCRAPER_API_KEY
```

This stores the environment variable name rather than the key in the MCP configuration. Start a new session and ask the client to list G Maps Crawl tools.

## Claude Code

```bash theme={null}
claude mcp add --transport http --scope user gmapscrawl \
  https://gmapscrawl.com/api/mcp \
  --header "Authorization: Bearer $GMSCRAPER_API_KEY"
```

The shell expands the variable before Claude Code writes its configuration. Keep that user configuration private; do not use project scope for a secret-bearing header.

## Configure your client

Supply the API key through your client's secret environment. The following is the common configuration shape; environment interpolation differs by client, so replace the placeholder using that client's secret mechanism.

```json theme={null}
{
  "mcpServers": {
    "gmapscrawl": {
      "url": "https://gmapscrawl.com/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "API-KEY": "YOUR_GMAPSCRAWL_API_KEY"
      }
    }
  }
}
```

REST and MCP accept `API-KEY` or a Bearer token. MCP also accepts `GMS-API-KEY` and `X-API-KEY`. Send one credential, not conflicting headers.

## Python SDK

Install the official Python MCP SDK and use the discovery example in [gmapscrawl-mcp](https://github.com/ricciflow-api/gmapscrawl-mcp):

```bash theme={null}
python3 -m pip install mcp
python3 examples/python/list_tools.py
```

The example reads `GMSCRAPER_API_KEY`, initializes a session, and lists tools without starting work.

## First tool call

Call `search_google_maps` with flat arguments:

```json theme={null}
{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "gl": "us",
  "extra": false,
  "client_request_id": "gmaps-example-search-20260922"
}
```

Use a new mutation identifier for a new search, preserving it and the arguments for retries. Read up to 20 businesses directly from structuredContent.businesses. Check the returned observation timestamps as described in [data freshness](/docs/concepts/freshness).

<Note>Use a key from the [API keys page](https://gmapscrawl.com/dashboard/api-keys); enter a name to create one, then copy it into your secret environment. New keys are live keys and requests use your API allowance. If you already have a test key, its results are simulated. A tool listing does not establish live access; check [availability](/docs/concepts/availability).</Note>

Example prompt: “Using my configured G Maps Crawl connection, request only page 1 for coffee shops in Seattle. Return up to 20 businesses from the response and report simulation state. Do not expand the search.”


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.