GridWhy
oficialHistórico de classificação em grade geográfica do Google Maps para SEO local: veja o histórico de varreduras, pergunte por que uma classificação mudou (concorrentes, avaliações, mudanças de categoria) e receba frases prontas para clientes e próximos passos, além de executar uma nova varredura em grade.
O que você pode fazer com GridWhy MCP?
- Revisar o histórico de varreduras — Consulte os locais e as palavras-chave monitorados com as varreduras mais recentes, incluindo as contagens de grade no top 20 e no top 3, a classificação média e a melhor classificação, além das varreduras manuais restantes.
- Explicar mudanças na classificação — Obtenha informações sobre por que uma palavra-chave mudou de posição entre as varreduras, considerando cobertura, concorrentes, velocidade de avaliações, nota e mudanças de categoria ou nome, com frases prontas para clientes.
- Iniciar uma varredura de grade — Inicie agora uma varredura para uma palavra-chave monitorada. Ela será descontada da sua cota de varreduras manuais e retornará um ID de varredura para acompanhamento.
- Conectar via OAuth ou chave — Adicione
https://gridwhy.com/mcpao Claude ou ao ChatGPT com login, ou use uma chavegw_no Claude Code, Cursor e em scripts.
Servidor MCP hospedado
npx add-mcp 'https://gridwhy.com/mcp'Instala no Claude Code, Codex, Cursor e outros
Documentação
Conecte com um clique
Claude e ChatGPT precisam apenas da URL https://gridwhy.com/mcp. Eles abrem uma página do GridWhy onde você faz login como de costume (link por e-mail ou Google) e escolhe o que o app pode fazer: ler (locais, histórico de varreduras, o que mudou) e fazer varreduras (iniciar varreduras, que usam sua cota de varreduras manuais). Não é preciso copiar nenhuma chave.
- Claude (claude.ai e o app para desktop, em qualquer plano): Customize → Connectors → Add → Add custom connector. Dê o nome GridWhy, cole
https://gridwhy.com/mcp, clique em Continue, mantenha as opções de autenticação que o Claude marcar como Detected (ele se registra automaticamente), clique em Add e depois em Connect. Nos planos Team e Enterprise, um Owner adiciona o conector em Organization settings → Connectors, e cada membro se conecta. - ChatGPT: acesse chatgpt.com/plugins, selecione + e depois Add custom MCP server. Digite GridWhy, cole
https://gridwhy.com/mcpem Connection, escolha OAuth para autenticação, confirme e selecione Create as a plugin. As políticas do seu workspace determinam se servidores personalizados são permitidos.
Os apps conectados aparecem em Settings → API and MCP, onde você pode desconectá-los; eles param de funcionar imediatamente. Eles têm os mesmos limites de uma chave de API (abaixo). Quando um período de avaliação termina ou uma assinatura é cancelada, eles retornam um erro claro até que você escolha um plano. Os nomes dos menus no Claude e no ChatGPT mudam de tempos em tempos; a URL permanece a mesma.
1. Ou use uma chave
Faça login, acesse Settings → API and MCP e crie uma chave. Ela começa com gw_ e é exibida uma única vez. Uma chave atua em todo o seu workspace; você pode revogá-la ali a qualquer momento.
Para Claude Code, Cursor, scripts e a API REST. Endpoint MCP: https://gridwhy.com/mcp (Streamable HTTP). Envie a chave como Authorization: Bearer gw_…. Descoberta OAuth para clientes compatíveis: https://gridwhy.com/.well-known/oauth-protected-resource/mcp.
2. Conecte seu cliente
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), depois reinicie
{
"mcpServers": {
"gridwhy": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://gridwhy.com/mcp", "--header", "Authorization:${GRIDWHY_AUTH}"],
"env": { "GRIDWHY_AUTH": "Bearer gw_your_key" }
}
}
}
Requer Node.js. A chave fica em uma variável de ambiente para que o espaço após “Bearer” seja preservado no Windows.
Cursor: ~/.cursor/mcp.json (ou.cursor/mcp.json em um projeto)
{
"mcpServers": {
"gridwhy": {
"url": "https://gridwhy.com/mcp",
"headers": { "Authorization": "Bearer gw_your_key" }
}
}
}
Modelos do ChatGPT pela API OpenAI Responses
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?"
}'
No app do ChatGPT, use a conexão com um clique acima; a chamada de API aqui recebe uma chave diretamente.
3. Ferramentas
get_historyLocais, palavras-chave monitoradas e suas varreduras, da mais recente para a mais antiga: quantos pontos da grade estão entre as 20 primeiras e as 3 primeiras posições, posição média e melhor posição, uma frase sobre “o que mudou” e um link para o relatório. Sem argumentos: todas as palavras-chave com a varredura mais recente, além das varreduras manuais restantes. Argumentos: location, keyword, keyword_id, limit (todos opcionais)explain_changePor que a classificação mudou entre uma varredura e a anterior: descobertas (cobertura, concorrentes que subiram ou apareceram, velocidade de avaliações, mudanças na classificação, categoria ou nome), cada uma com uma frase para enviar ao cliente, além dos próximos passos. Informe scan_id ou um local e uma palavra-chave para obter a varredura concluída mais recente. Argumentos: scan_id, location, keyword, keyword_id (todos opcionais)run_scanInicia agora uma varredura da grade para uma palavra-chave monitorada (além da programação). Conta para as varreduras manuais da conta (por dia e por 30 dias); a primeira varredura de uma palavra-chave é gratuita. Leva de 15 a 30 segundos; depois, chame explain_change com o scan_id retornado. Argumentos: location, keyword, keyword_id (todos opcionais)
Experimente: “Explique o que mudou para a Wilson Plumbing em ‘plumber’ e escreva a atualização para o cliente.”
4. REST
As mesmas três operações, a mesma chave, os mesmos limites e as mesmas respostas (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; a varredura leva de 15 a 30 segundos)
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" }'
Os erros são retornados como { "error": "…" } com os códigos 400, 401, 403, 404, 409 ou 429 (com Retry-After).
5. Limites
| Plano | Chamadas de API por hora | run_scan (varreduras manuais) |
|---|---|---|
| Solo | 100 | 5 por dia, 30 a cada 30 dias |
| Agency | 500 | 20 por dia, 100 a cada 30 dias |
| Agency+ | 2.000 | 50 por dia, 250 a cada 30 dias |
As varreduras programadas nunca são limitadas pela API. O período de avaliação gratuito tem os limites do Solo. Uma chave para de funcionar quando o período de avaliação termina ou uma assinatura é cancelada.