Google Search Console MCP

GSC SEO MCP

Conecte o Google Search Console ao Cursor, Claude ou Gemini. Faça perguntas em português simples e receba dados reais de SEO.

---

O que você pode perguntar à sua IA depois de configurado

Show me the biggest SEO opportunities for my site.
Which pages are losing clicks?
Find keywords ranking positions 4–15 that I can push to page 1.
Split branded vs non-branded traffic for the last 90 days.
Which pages have bad CTR for their ranking position?
Inspect these URLs and tell me what's wrong with indexing.
Generate a Markdown SEO report for the last 28 days.

---

Configuração

Há duas partes:

1. Google — dê ao MCP acesso aos dados do seu Search Console
2. Seu aplicativo de IA — informe ao Cursor / Claude / Gemini como executá-lo

Escolha primeiro seu método de autenticação do Google:

	Conta de serviço	OAuth
Melhor para	Agências, sites de clientes, equipes	Sites pessoais, sua própria conta
Como funciona	Arquivo de chave JSON, sem login no navegador	Faz login via navegador uma vez
Recomendado?	Sim, mais simples para MCP	Também funciona

---

Parte 1 — Configuração do Google

Etapa 1: Criar um projeto no Google Cloud

Isso é apenas um contêiner para acesso à API. Não é o seu site.

1. Acesse console.cloud.google.com
2. Clique no menu suspenso de projetos no topo → Novo projeto
3. Nomeie-o como GSC SEO MCP e clique em Criar
4. Certifique-se de que ele esteja selecionado no menu suspenso superior após a criação

Etapa 2: Ativar a API do Search Console

1. Acesse APIs e serviços → Biblioteca
2. Pesquise Google Search Console API → clique nela → clique em Ativar
3. Opcional: ative também a Indexing API se quiser as ferramentas indexing_* (útil apenas para páginas de JobPosting/transmissão ao vivo)

---

Opção A: Conta de serviço (recomendada)

1. Criar a conta de serviço

1. Acesse IAM e administrador → Contas de serviço
2. Clique em Criar conta de serviço
3. Nome: gsc-seo-mcp → clique em Criar e continuar
4. Pule a atribuição de função → clique em Continuar → clique em Concluído
5. Copie o e-mail da conta de serviço — que se parece com:

   gsc-seo-mcp@your-project-id.iam.gserviceaccount.com
   

2. Baixar o arquivo de chave

1. Clique na conta de serviço que você acabou de criar
2. Acesse a aba Chaves → Adicionar chave → Criar nova chave → JSON → Criar
3. O Google baixa um arquivo .json — salve-o em um local seguro, como:
   • Mac/Linux: /Users/your-name/keys/gsc-seo-mcp.json
   • Windows: C:/Users/your-name/keys/gsc-seo-mcp.json

Não envie este arquivo para o GitHub. Trate-o como uma senha.

3. Adicioná-lo ao Search Console

1. Abra search.google.com/search-console
2. Selecione sua propriedade
3. Acesse Configurações → Usuários e permissões → Adicionar usuário
4. Cole o e-mail da conta de serviço, defina a permissão como Total, clique em Adicionar

Você precisa ser proprietário da propriedade para fazer isso.

4. Sua configuração do MCP

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/gsc-seo-mcp.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Dica para caminho no Windows — use barras normais ou barras invertidas duplas:

"GSC_KEY_FILE": "C:/Users/your-name/keys/gsc-seo-mcp.json"

---

Opção B: OAuth (entrar com o Google)

Use esta opção se quiser conectar com sua própria conta do Google via login no navegador.

1. Configurar a tela de consentimento OAuth

1. Acesse APIs e serviços → Tela de consentimento OAuth
2. Escolha Externo (funciona para contas Gmail) → preencha nome do aplicativo, e-mail → salve
3. Se o aplicativo estiver em modo de teste, adicione seu Gmail em Usuários de teste

2. Criar o cliente OAuth

1. Acesse APIs e serviços → Credenciais → Criar credenciais → ID do cliente OAuth
2. Tipo de aplicativo: Aplicativo de desktop → nomeie-o como GSC SEO MCP Desktop → clique em Criar
3. Clique em Baixar JSON — salve-o como:
   • Mac/Linux: /Users/your-name/keys/gsc-oauth-client.json
   • Windows: C:/Users/your-name/keys/gsc-oauth-client.json

3. Sua configuração do MCP

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "oauth",
        "GSC_OAUTH_SECRETS_FILE": "/absolute/path/to/gsc-oauth-client.json",
        "GSC_TOKEN_FILE": "/absolute/path/to/gsc-oauth-token.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

GSC_TOKEN_FILE é onde o MCP salva seu token de login após o primeiro login no navegador. Se você omitir, ele salva em ~/.gsc-seo-mcp/token.json por padrão.

4. Primeira execução

Reinicie seu cliente MCP e peça para executar server_health ou list_properties. Uma janela do navegador abrirá — entre com o Google e aprove o acesso. Pronto, não é necessário repetir o login.

Se o Google mostrar um aviso de "aplicativo não verificado", clique em Avançado → Continuar — este é seu próprio aplicativo OAuth, tudo bem.

---

Parte 2 — Adicionar ao seu aplicativo de IA

Node.js 20+ é necessário. Baixe aqui se você não tiver.

Cursor

Crie .cursor/mcp.json na pasta do seu projeto (ou use as configurações globais do MCP):

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com",
        "GSC_BRAND_TERMS": "mybrand,mybrand.com"
      }
    }
  }
}

Claude Desktop

Edite claude_desktop_config.json:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar.

Claude Code

Crie .mcp.json no seu projeto:

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Ou via CLI:

claude mcp add --transport stdio \
  --env GSC_AUTH_MODE=service_account \
  --env GSC_KEY_FILE=/absolute/path/to/service-account.json \
  --env GSC_SITE_URL=sc-domain:example.com \
  gsc-seo -- npx -y gsc-seo-mcp

Gemini CLI

Edite ~/.gemini/settings.json (ou .gemini/settings.json no seu projeto):

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      },
      "timeout": 120000,
      "trust": false
    }
  }
}

---

Formato da URL da propriedade

Use o formato exato do Search Console:

sc-domain:example.com        ← domain property (recommended)
https://www.example.com/     ← URL-prefix property (include the trailing slash)

---

Todas as variáveis de configuração

Variável	Obrigatória	O que faz
GSC_SITE_URL	Recomendada	Propriedade padrão. Exemplo: sc-domain:example.com
GSC_SITE_URLS	Opcional	Propriedades separadas por vírgula para painéis multi-site
GSC_AUTH_MODE	Opcional	service_account ou oauth. Detectada automaticamente quando possível
GSC_KEY_FILE	Conta de serviço	Caminho para a chave JSON da conta de serviço
GOOGLE_APPLICATION_CREDENTIALS	Conta de serviço	Variável de caminho alternativa
GSC_OAUTH_SECRETS_FILE	OAuth	Caminho para o JSON do segredo do cliente OAuth
GSC_OAUTH_CLIENT_ID	Alternativa OAuth	ID do cliente se não usar um arquivo de segredos
GSC_OAUTH_CLIENT_SECRET	Alternativa OAuth	Segredo do cliente se não usar um arquivo de segredos
GSC_TOKEN_FILE	Opcional	Onde o token OAuth é salvo após o login
GSC_BRAND_TERMS	Opcional	Termos de marca separados por vírgula para brand_nonbrand_split
GSC_REPORT_DIR	Opcional	Pasta para relatórios Markdown. Padrão: ./reports
GSC_DATA_STATE	Opcional	all, final ou hourly_all. Padrão: all

---

Ferramentas

Principais

Ferramenta	O que faz
server_health	Mostra status da configuração, modo de autenticação e contagem de ferramentas
list_properties	Lista todas as propriedades do Search Console às quais você tem acesso
get_site	Obtém detalhes de permissão para uma propriedade
add_site	Adiciona um site à sua conta
delete_site	Remove um site da sua conta

Análise de pesquisa

Ferramenta	O que faz
search_analytics	Consulta completa com dimensões, filtros, tipo de pesquisa e estado dos dados
advanced_filter_query	Puxa até 50.000 linhas para auditorias mais profundas
top_queries	Principais consultas, opcionalmente filtradas por página
top_pages	Principais páginas, opcionalmente filtradas por consulta
performance_overview	Visão geral do site com comparação de períodos, tendência diária, dispositivos
compare_periods	Período atual vs. anterior por página, consulta, país ou dispositivo
dimension_breakdown	Desempenho por uma dimensão
page_query_matrix	Mapeia páginas para as consultas que as geram

Análise de SEO

Ferramenta	O que responde
quick_wins	Quais palavras-chave estão próximas o suficiente para melhorar rápido?
ctr_opportunities	Quais snippets têm desempenho abaixo do esperado para sua posição?
content_decay	Quais páginas estão em declínio em vários períodos?
traffic_drop_diagnosis	A queda foi em rankings, CTR, demanda, cobertura ou mista?
cannibalization_check	Quais consultas estão divididas entre páginas concorrentes?
brand_nonbrand_split	Quanto tráfego é de marca vs. não-marca?
search_intent_breakdown	Como as consultas se dividem entre informacional, comercial, transacional, navegacional, local?
device_country_opportunities	Quais segmentos de dispositivo/país/página têm CTR ou ranking fraco?
long_tail_questions	Quais consultas em formato de pergunta merecem expansão de conteúdo?
page_refresh_priorities	Quais páginas devem ser atualizadas primeiro?
internal_link_opportunities	Quais páginas fortes podem apoiar páginas mais fracas?
query_page_fit	Pelo que uma página ranqueia e o conteúdo corresponde?
title_meta_brief	Quais consultas devem informar atualizações de título/meta?
anomaly_alerts	Quais páginas tiveram perdas anormais recentemente?

Indexação, Sitemaps, URLs

Ferramenta	O que faz
inspect_url	Verifica uma URL quanto a status de indexação, canônica, rastreamento, cobertura
batch_inspect_urls	Inspeciona várias URLs
index_coverage_summary	Resume resultados de inspeção em uma lista de URLs
list_sitemaps	Lista sitemaps enviados com erros e contagens indexadas
get_sitemap	Detalhes de um sitemap
submit_sitemap	Envia ou atualiza um sitemap
delete_sitemap	Exclui um sitemap enviado
indexing_publish_url	Envia uma notificação da Indexing API para uma URL elegível
indexing_batch_publish	Envia várias notificações da Indexing API
indexing_get_metadata	Verifica o status mais recente da notificação da Indexing API para uma URL

Relatórios

Ferramenta	O que faz
multi_site_dashboard	Compara várias propriedades em uma única visualização
generate_markdown_report	Salva um relatório de SEO em Markdown no disco
verify_claim	Re-consulta o GSC para verificar um número antes de reportá-lo a um cliente

---

Solução de problemas

As ferramentas não aparecem no meu aplicativo de IA Certifique-se de que o Node.js 20+ esteja instalado. Verifique se sua configuração do MCP usa npx -y gsc-seo-mcp exatamente. Todos os caminhos de arquivo devem ser absolutos (não ~/ ou relativos).

A conta de serviço não mostra propriedades Você precisa adicionar o e-mail da conta de serviço ao Search Console em Configurações → Usuários e permissões.

A inspeção de URL falha A URL deve pertencer à propriedade em GSC_SITE_URL. Para propriedades de prefixo de URL, use o prefixo exato com protocolo e barra final.

O OAuth não abre o navegador Defina GSC_OAUTH_PORT=0 para permitir que ele escolha uma porta livre. Se você estiver em uma máquina remota, precisará executar isso localmente.

---

Notas sobre dados

• As linhas do Search Analytics são ordenadas por cliques. A API tem limites internos de linhas, então nem toda linha possível está incluída.
• GSC_DATA_STATE=all inclui dados recentes. Use final para números finais de relatórios.
• A inspeção de URL mostra o estado de indexação do Google, não um rastreamento ao vivo.
• A Indexing API é apenas para páginas de JobPosting e BroadcastEvent — não é um atalho geral de indexação.

---

Segurança

• Nunca envie chaves de conta de serviço, segredos OAuth ou arquivos de token para o Git.
• Use permissões somente leitura do Search Console se você não precisar de ferramentas de escrita.
• Revise as chamadas delete_site, delete_sitemap, submit_sitemap e indexing_publish_url antes de aprová-las.

---

Documentação oficial

• Criar um projeto no Google Cloud
• Ativar APIs
• Criar credenciais
• Usuários e permissões do Search Console
• API de Search Analytics
• API de inspeção de URL
• Indexing API
• Model Context Protocol

---

Licença

MIT. Se isso economizar seu tempo, dê uma estrela no repositório.