Erros de configuração do MCP do Search Console
Como corrigir os erros dos servidores MCP do Search Console: API não ativada, permissão 403, sc-domain, acesso bloqueado, invalid_grant, spawn uvx ENOENT.
Por Denis Veisllari
A maioria dos erros de MCP do Google Search Console vem de cinco lugares: o projeto no Google Cloud, a propriedade do Search Console, a tela de consentimento do OAuth, o arquivo de credenciais e a configuração do cliente de IA. Encontre a sua mensagem de erro abaixo, corrija esse passo e reinicie o cliente. Se você prefere pular o Google Cloud de vez, a última seção mostra o caminho que só exige um login do Google.
O Google não publicou um servidor MCP oficial do Search Console. O repositório de MCP do Google cobre Google Analytics, BigQuery, Maps e outros produtos, mas não o Search Console, então todo servidor de Search Console que você pode instalar é um projeto comunitário. Os dois mais usados são o mcp-gsc (instalado como mcp-search-console) e o mcp-server-gsc. Os erros abaixo valem para os dois e para a maioria dos outros.
Consulta rápida
| O que aparece | Causa provável | Ir para |
|---|---|---|
| "has not been used in project ... before or it is disabled" | A API do Search Console está desligada nesse projeto do Cloud | API não ativada |
| 403 "User does not have sufficient permission for site" | Conta de serviço não adicionada à propriedade, ou URL errada | Erros de permissão |
| "is not a verified Search Console site in this account" | Confusão entre propriedade de domínio e de prefixo de URL | Formato de propriedade errado |
| "Failed to add user: email not found" no Search Console | Bug do Google com contas de serviço novas | E-mail não encontrado |
| "Access blocked" ou "Error 403: access_denied" na tela do Google | App OAuth em modo Testing e você não é usuário de teste | Erros na tela do OAuth |
invalid_grant mais ou menos uma semana depois de ter funcionado | Tokens de atualização em modo Testing expiram após 7 dias | Funciona e depois para |
| "Error 400: redirect_uri_mismatch" | Cliente web usado onde é preciso um cliente de desktop | Erros na tela do OAuth |
| "Service account credentials file not found" | Caminho relativo ou pacote errado | Arquivo de credenciais |
spawn uvx ENOENT ou spawn npx ENOENT | O cliente não encontra o comando | Erros do cliente |
| Nenhuma ferramenta aparece e nenhum log é gravado | Python anterior ao 3.11 | Erros do cliente |
| Os números não batem com o painel do Search Console | Atraso dos dados, limites de linhas, consultas anonimizadas | Os números não batem |
A API não está ativada
O erro é um 403 dizendo que a Google Search Console API "has not been used in project", seguido de um número de projeto, muitas vezes com um link para ativá-la.
A API precisa estar ativada no mesmo projeto do Cloud a que pertencem o seu cliente OAuth ou a sua conta de serviço. O erro comum é ativá-la em outro projeto.
- Compare o número do projeto no erro com o projeto do seu JSON de credenciais.
- No Google Cloud, abra APIs & Services > Library nesse projeto e ative a Google Search Console API.
- Espere alguns minutos e tente de novo. O Google avisa que novas configurações podem demorar um pouco para chegar aos sistemas dele.
Erros de permissão
O erro é um 403 "User does not have sufficient permission for site". Na inspeção de URL aparece "The caller does not have permission".
Criar uma conta de serviço não dá a ela nenhum acesso ao Search Console. O e-mail dela precisa ser adicionado à propriedade exata que você consulta.
- Abra a chave JSON da conta de serviço e copie o valor de
client_email. - No Search Console, abra Settings > Users and permissions > Add user, cole o e-mail e dê permissão total (Full).
- Se você entra com OAuth, use uma conta do Google que já vê a propriedade no Search Console.
Se a conta tem acesso e o 403 continua, provavelmente a string da propriedade está errada. Leia a próxima seção.
O formato da propriedade está errado
O erro é "'sc-domain:example.com' is not a verified Search Console site in this account", ou o mesmo 403 de antes.
O Search Console tem dois tipos de propriedade, e a API quer a string exata do tipo que você tem:
- Propriedade de domínio:
sc-domain:example.com - Propriedade de prefixo de URL: a URL completa com protocolo e barra no final, como
https://www.example.com/
http e https são propriedades diferentes, assim como www e o domínio sem www. Não tente adivinhar. Peça ao agente para rodar a ferramenta do servidor que lista os sites e copie a URL do site exatamente como ela vier.
O Search Console diz que o e-mail da conta de serviço não foi encontrado
Quando você adiciona a conta de serviço como usuário, o Search Console responde "Failed to add user: email not found."
É um problema do Google com contas de serviço recém-criadas, não algo que você fez. Foi relatado pela primeira vez por volta de abril de 2026, voltou em setembro de 2026 e também afeta o Google Analytics. O Google reconheceu o problema, mas não deu data para a correção. Os usuários relatam três formas de contornar:
- Esperar de algumas horas a um dia e adicionar o usuário de novo.
- Adicionar o usuário pela API em vez da tela do Search Console.
- Usar OAuth em vez de conta de serviço, se o seu servidor aceitar.
Erros na tela do OAuth
"Access blocked" com "Error 403: access_denied". A sua tela de consentimento está em modo Testing e a conta do Google com que você entrou não é usuário de teste. No Google Cloud, abra Google Auth Platform > Audience > Test users e adicione o seu próprio endereço.
"Google hasn't verified this app". Aparece quando um app não verificado pede acesso ao Search Console. Se você mesmo criou o projeto no Cloud e só você usa, pode seguir em frente apesar do aviso. A verificação só importa se você entregar o app para outras pessoas.
"Error 400: redirect_uri_mismatch". Você criou um cliente OAuth do tipo "Web application", mas servidores locais fazem login por um endereço de loopback como http://localhost com uma porta aleatória. Crie um novo cliente OAuth do tipo Desktop app, baixe o JSON dele e aponte o servidor para ele. No mcp-gsc, essa é a configuração GSC_OAUTH_CLIENT_SECRETS_FILE.
Funcionou e parou uma semana depois
O erro é invalid_grant, normalmente "Token has been expired or revoked."
O Google expira os tokens de atualização após 7 dias quando a tela de consentimento de um app externo ainda está em modo Testing. Os tokens também morrem se você revogar o acesso ou se ficarem seis meses sem uso.
- No Google Cloud, mude o status de publicação da tela de consentimento para In production. Para uso pessoal, ela pode continuar sem verificação.
- Apague o arquivo de token que o servidor salvou.
- Faça login de novo.
Se você usa o mcp-gsc, atualize também. Versões anteriores à 0.4.2 podiam falhar ao renovar tokens somente leitura e apagar o arquivo de token.
O arquivo de credenciais não é encontrado
O erro é "Service account credentials file not found."
- Caminho relativo. Ferramentas como o uvx rodam o servidor a partir de uma pasta de cache, então um caminho como
./key.jsonnão aponta para lugar nenhum. Use o caminho completo na configuração do cliente. No Windows, duplique as barras invertidas:C:\\Users\\you\\key.json. - Pacote errado. Para o mcp-gsc, instale
mcp-search-console, não o pacotemcp-gscdo PyPI, que não tem relação nenhuma. Rode comouvx mcp-search-console@latestpara ter a versão atual. - Arquivo errado na configuração errada. Uma chave de conta de serviço contém
"type": "service_account"e umclient_email. Um arquivo de cliente OAuth começa com uma chaveinstalledouweb. Cada um vai na sua própria configuração: o mcp-gsc usaGSC_CREDENTIALS_PATHpara o primeiro eGSC_OAUTH_CLIENT_SECRETS_FILEpara o segundo, e o mcp-server-gsc usaGOOGLE_APPLICATION_CREDENTIALS.
O cliente não consegue iniciar o servidor
spawn uvx ENOENT ou spawn npx ENOENT. Apps de desktop não carregam o PATH do seu terminal, então não encontram o comando. Coloque o caminho completo em "command". Descubra qual é com which uvx no macOS ou Linux, ou where uvx no Windows. Para npx no Windows, use "command": "cmd" com os argumentos ["/c", "npx", "-y", ...].
Nenhuma ferramenta e nenhum arquivo de log. O mcp-gsc exige Python 3.11 ou mais recente e falha em silêncio em versões mais antigas. Rode pelo uvx, que escolhe um Python adequado para você, ou instale o Python 3.12.
Mudanças na configuração não fazem efeito. Procure no JSON vírgulas sobrando no final e barras invertidas sem escape, depois feche o app por completo e abra de novo. No Mac, fechar a janela não basta; use Cmd+Q.
Onde ficam os logs:
- Claude Desktop no macOS:
~/Library/Logs/Claude. Omcp.logregistra falhas de conexão, e omcp-server-<name>.logregistra os erros do próprio servidor. - Claude Desktop no Windows:
%APPDATA%\Claude\logs. - Claude Code: rode
claude mcp get <name>para ver o erro, ou/mcpdentro de uma sessão. - Cursor: abra o painel Output e escolha MCP Logs.
Mais um limite: servidores locais só rodam em apps de desktop e de terminal. Eles não funcionam no claude.ai pelo navegador nem no ChatGPT, que exigem um servidor remoto.
Os números não batem com o painel
Não são erros, mas explicam a maioria das reclamações de que "o agente errou".
- Atraso. Os dados do Search Console costumam chegar depois de dois ou três dias, e os dias mais recentes ainda podem mudar. Alguns servidores pedem só dados finais, então os últimos dias aparecem vazios.
- Limites de linhas. Uma requisição à API retorna no máximo 25.000 linhas, e o Google expõe no máximo 50.000 linhas por dia por tipo de busca. Em um site grande, as consultas de cauda longa ficam de fora.
- Consultas faltando. Consultas raras e pessoais ficam de fora, então as linhas de consultas nunca somam o total de cliques. Para totais exatos, peça os dados sem a dimensão de consulta ou de página.
- Totais diferentes. O gráfico soma por propriedade e a tabela por página, então os dois podem não bater. Confira também o período; os dados por hora usam o horário do Pacífico.
- Cotas. A inspeção de URL permite 2.000 verificações por dia por site, então inspeções em lote num site grande param no meio. O Search Analytics permite 1.200 consultas por minuto por site.
Pule o Google Cloud de vez
Todos os erros acima, exceto os da última seção, vêm de manter o seu próprio projeto no Google Cloud. O MCP do Google Search Console do zaDojo já é hospedado: você conecta o Search Console num projeto do zaDojo com um login normal do Google, e o seu agente lê os dados em https://app.zadojo.com/mcp. Não há projeto no Cloud, API para ativar, conta de serviço, tela de consentimento nem arquivo de credenciais, e ele funciona no claude.ai e no ChatGPT, além dos clientes de desktop.
Leituras do Search Console, inspeção de URL e cobertura de indexação são grátis no plano gratuito do zaDojo, que não pede cartão. O mesmo vale para as leituras do Google Analytics e para auditorias de até 50 páginas. Dados de palavras-chave, concorrentes e visibilidade em IA usam créditos. Para comparar com as outras opções grátis, veja servidores MCP de SEO grátis.
Perguntas frequentes
Existe um servidor MCP oficial do Google Search Console? Não. O Google publica servidores MCP para o Google Analytics e outros produtos, mas não para o Search Console. Todo servidor de Search Console é um projeto comunitário ou um serviço hospedado.
Uso conta de serviço ou OAuth? Uma conta de serviço é boa para um servidor que roda sem supervisão, mas você precisa adicionar o e-mail dela a cada propriedade. O OAuth usa a sua própria conta do Google e vê todas as propriedades que você já tem, mas em modo Testing você precisa fazer login de novo a cada 7 dias até mudar para In production.
Por que o meu agente só vê alguns dos meus sites? A conta ou a conta de serviço que ele usa só vê as propriedades às quais foi adicionada. Peça ao agente para listar os sites e compare essa lista com o Search Console.
Um servidor MCP do Search Console pode alterar o meu site? Não. Esses servidores leem e gerenciam dados do Search Console. Nenhum deles edita as suas páginas.