GridWhy

official

Google Maps geo-grid rank history for local SEO: see scan history, ask why a ranking changed (competitors, reviews, category changes) with client-ready lines and next steps, and run a new grid scan.

What can you do with GridWhy MCP?

  • Review scan history — Ask for tracked locations and keywords with their latest scans, including top-20 and top-3 grid counts, average and best rank, and remaining manual scans.
  • Explain ranking changes — Get findings on why a keyword moved between scans, covering coverage, competitors, review velocity, rating, and category or name changes, with client-ready lines.
  • Start a grid scan — Trigger a scan for one tracked keyword now, which counts against your manual scan allowance and returns a scan ID for follow-up.
  • Connect via OAuth or key — Add https://gridwhy.com/mcp in Claude or ChatGPT with sign-in, or use a gw_ key for Claude Code, Cursor, and scripts.

Hosted MCP Server

npx add-mcp 'https://gridwhy.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Connect with one click

Claude and ChatGPT only need the URL https://gridwhy.com/mcp. They open a GridWhy page where you sign in as usual (email link or Google) and choose what the app may do: read (locations, scan history, what changed) and scan (start scans, which use your manual scan allowance). No key to copy.

  1. Claude (claude.ai and the desktop app, any plan): Customize → Connectors → Add → Add custom connector. Name it GridWhy, paste https://gridwhy.com/mcp, click Continue, keep the authentication options Claude marks Detected (it registers itself automatically), click Add, then Connect. On Team and Enterprise plans an Owner adds it under Organization settings → Connectors and each member connects.
  2. ChatGPT: open chatgpt.com/plugins, select +, then Add custom MCP server. Enter GridWhy, paste https://gridwhy.com/mcp under Connection, choose OAuth for authentication, confirm, and select Create as a plugin. Your workspace's policies decide whether custom servers are allowed.

Connected apps are listed under Settings → API and MCP, where you can disconnect them; they stop working at once. They have the same limits as an API key (below). When a trial ends or a subscription is canceled, they get a clear error until you pick a plan. Menu names in Claude and ChatGPT change from time to time; the URL stays the same.

1. Or use a key

Sign in, open Settings → API and MCP and create a key. It starts with gw_ and is shown once. A key acts for your whole workspace; revoke it there at any time.

For Claude Code, Cursor, scripts and the REST API. MCP endpoint: https://gridwhy.com/mcp (Streamable HTTP). Send the key as Authorization: Bearer gw_…. OAuth discovery for clients that support it: https://gridwhy.com/.well-known/oauth-protected-resource/mcp.

2. Connect your client

Claude Code (terminal)

claude mcp add --transport http gridwhy https://gridwhy.com/mcp \
  --header "Authorization: Bearer gw_your_key"

Claude Desktop: Settings → Developer → Edit config (claude_desktop_config.json), then restart

{
  "mcpServers": {
    "gridwhy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://gridwhy.com/mcp", "--header", "Authorization:${GRIDWHY_AUTH}"],
      "env": { "GRIDWHY_AUTH": "Bearer gw_your_key" }
    }
  }
}

Needs Node.js. The key sits in an environment variable so the space after “Bearer” survives on Windows.

Cursor: ~/.cursor/mcp.json (or.cursor/mcp.json in a project)

{
  "mcpServers": {
    "gridwhy": {
      "url": "https://gridwhy.com/mcp",
      "headers": { "Authorization": "Bearer gw_your_key" }
    }
  }
}

ChatGPT models through the OpenAI Responses API

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "gridwhy",
      "server_url": "https://gridwhy.com/mcp",
      "headers": { "Authorization": "Bearer gw_your_key" },
      "require_approval": { "never": { "tool_names": ["get_history", "explain_change"] } }
    }],
    "input": "Which of my clients lost ground on Google Maps this week, and why?"
  }'

Inside the ChatGPT app, use the one-click connection above instead; the API call here takes a key directly.

3. Tools

  • get_history Locations, tracked keywords and their scans, newest first: how many grid points rank in the top 20 and top 3, average and best rank, the one-line 'what changed', and a report link. Without arguments: every keyword with its latest scan, plus the manual scans left. Arguments: location, keyword, keyword_id, limit (all optional)
  • explain_change Why the ranking changed between a scan and the one before it: findings (coverage, competitors that rose or appeared, review velocity, rating, category or name changes), each with a line to paste to the client, plus next steps. Pass scan_id, or a location and keyword for their latest finished scan. Arguments: scan_id, location, keyword, keyword_id (all optional)
  • run_scan Starts a grid scan for one tracked keyword now (in addition to the schedule). Counts against the account's manual scans (per day and per 30 days); a keyword's first scan is free. Takes 15-30 seconds; then call explain_change with the returned scan_id. Arguments: location, keyword, keyword_id (all optional)

Try: “Explain what changed for Wilson Plumbing on ‘plumber’ and write the update for the client.”

4. REST

The same three operations, the same key, limits and answers (JSON).

get_history

curl "https://gridwhy.com/api/v1/history?location=Wilson&keyword=plumber&limit=5" \
  -H "Authorization: Bearer gw_your_key"

explain_change

curl "https://gridwhy.com/api/v1/explain?scan_id=<scan id>" \
  -H "Authorization: Bearer gw_your_key"

run_scan (202 Accepted; the scan takes 15–30 seconds)

curl -X POST "https://gridwhy.com/api/v1/scans" \
  -H "Authorization: Bearer gw_your_key" -H "Content-Type: application/json" \
  -d '{ "location": "Wilson Plumbing", "keyword": "plumber" }'

Errors come back as { "error": "…" } with 400, 401, 403, 404, 409 or 429 (with Retry-After).

5. Limits

PlanAPI calls an hourrun_scan (manual scans)
Solo1005 a day, 30 per 30 days
Agency50020 a day, 100 per 30 days
Agency+2,00050 a day, 250 per 30 days

Scheduled scans are never limited by the API. The free trial has Solo’s limits. A key stops working when a trial ends or a subscription is canceled.