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 apareceCausa provávelIr para
"has not been used in project ... before or it is disabled"A API do Search Console está desligada nesse projeto do CloudAPI não ativada
403 "User does not have sufficient permission for site"Conta de serviço não adicionada à propriedade, ou URL erradaErros de permissão
"is not a verified Search Console site in this account"Confusão entre propriedade de domínio e de prefixo de URLFormato de propriedade errado
"Failed to add user: email not found" no Search ConsoleBug do Google com contas de serviço novasE-mail não encontrado
"Access blocked" ou "Error 403: access_denied" na tela do GoogleApp OAuth em modo Testing e você não é usuário de testeErros na tela do OAuth
invalid_grant mais ou menos uma semana depois de ter funcionadoTokens de atualização em modo Testing expiram após 7 diasFunciona e depois para
"Error 400: redirect_uri_mismatch"Cliente web usado onde é preciso um cliente de desktopErros na tela do OAuth
"Service account credentials file not found"Caminho relativo ou pacote erradoArquivo de credenciais
spawn uvx ENOENT ou spawn npx ENOENTO cliente não encontra o comandoErros do cliente
Nenhuma ferramenta aparece e nenhum log é gravadoPython anterior ao 3.11Erros do cliente
Os números não batem com o painel do Search ConsoleAtraso dos dados, limites de linhas, consultas anonimizadasOs 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.

  1. Compare o número do projeto no erro com o projeto do seu JSON de credenciais.
  2. No Google Cloud, abra APIs & Services > Library nesse projeto e ative a Google Search Console API.
  3. 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.

  1. Abra a chave JSON da conta de serviço e copie o valor de client_email.
  2. No Search Console, abra Settings > Users and permissions > Add user, cole o e-mail e dê permissão total (Full).
  3. 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.

  1. 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.
  2. Apague o arquivo de token que o servidor salvou.
  3. 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.json nã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 pacote mcp-gsc do PyPI, que não tem relação nenhuma. Rode como uvx mcp-search-console@latest para ter a versão atual.
  • Arquivo errado na configuração errada. Uma chave de conta de serviço contém "type": "service_account" e um client_email. Um arquivo de cliente OAuth começa com uma chave installed ou web. Cada um vai na sua própria configuração: o mcp-gsc usa GSC_CREDENTIALS_PATH para o primeiro e GSC_OAUTH_CLIENT_SECRETS_FILE para o segundo, e o mcp-server-gsc usa GOOGLE_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. O mcp.log registra falhas de conexão, e o mcp-server-<name>.log registra 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 /mcp dentro 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.