GridWhy
officialGoogle 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/mcpin Claude or ChatGPT with sign-in, or use agw_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.
- 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. - ChatGPT: open chatgpt.com/plugins, select +, then Add custom MCP server. Enter GridWhy, paste
https://gridwhy.com/mcpunder 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_historyLocations, 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_changeWhy 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_scanStarts 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
| Plan | API calls an hour | run_scan (manual scans) |
|---|---|---|
| Solo | 100 | 5 a day, 30 per 30 days |
| Agency | 500 | 20 a day, 100 per 30 days |
| Agency+ | 2,000 | 50 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.