Google Search Console MCP Server (Cloud Run / SSE) 🚀

Servidor Model Context Protocol (MCP) para o Google Search Console (GSC), projetado para rodar de forma serverless no Google Cloud Run utilizando transporte SSE (Server-Sent Events) via HTTP.

Permite conectar ferramentas de Inteligência Artificial como Claude (Desktop & Web), Cursor, Antigravity e outros clientes MCP diretamente às métricas e dados de indexação dos seus sites no Google Search Console.

📋 Sumário

• Recursos e Ferramentas Disponíveis

• Arquitetura e Segurança DevSecOps

• Pré-requisitos

• Passo a Passo: Obtenção de Credenciais no Google

• Deploy Automatizado no Cloud Run

• Como Conectar aos Clientes MCP

  • Claude Desktop

  • Claude Web

  • Cursor IDE

  • Google Antigravity

• Exemplos Práticos de Prompts para SEO

• Desenvolvimento Local

• Segurança

• Licença

🛠 Recursos e Ferramentas Disponíveis

O servidor disponibiliza 3 ferramentas oficiais do MCP para o seu assistente de IA:

🏗 Arquitetura e Segurança DevSecOps

┌─────────────────────────────────┐
│   MCP Client (Claude / Cursor)  │
└───────────────┬─────────────────┘
                │ HTTP SSE (com ?apiKey=...)
                ▼
┌─────────────────────────────────┐
│   Google Cloud Run (Express)    │
│   - Escala a zero (custo zero)  │
│   - Validação de API Key        │
└───────┬─────────────────┬───────┘
        │                 │
        ▼                 ▼
┌──────────────┐   ┌──────────────────────────┐
│ Secret       │   │ Google Search Console    │
│ Manager      │   │ API v1 (readonly)        │
└──────────────┘   └──────────────────────────┘

• Zero Credenciais Expostas: Nenhuma senha ou chave reside em texto plano no container. Todos os segredos são provisionados via Google Cloud Secret Manager.

• Autenticação no Endpoint: O servidor pode gerar e exigir uma chave secreta MCP_API_KEY. Requisições sem a chave correta são bloqueadas imediatamente (401 Unauthorized).

• Escopo Restrito: O servidor utiliza apenas o escopo de leitura https://www.googleapis.com/auth/webmasters.readonly. Não há permissão para alterar propriedades, deletar sites ou submeter sitemaps.

• Custo Praticamente Zero: No Cloud Run, instâncias escalam para 0 quando ociosas. O nível gratuito da Google Cloud cobre até 2 milhões de requisições por mês.

📦 Pré-requisitos

1. Conta no Google Cloud Platform (GCP) com faturamento ativado (o uso dentro do Free Tier não gera cobranças).

2. Propriedade verificada no Google Search Console.

3. Google Cloud SDK (gcloud CLI) instalado na sua máquina (Instruções de instalação).

4. Node.js 18+ instalado (para testes locais ou deploy com compilação local).

🔑 Passo a Passo: Obtenção de Credenciais no Google

Você pode autenticar de duas formas: Opção A (OAuth 2.0 - Recomendada) ou Opção B (Service Account).

Opção A: OAuth 2.0 (Recomendado para usuários individuais e agências)

1. Acesse o Google Cloud Console.

2. Crie um novo projeto (ex: meu-gsc-mcp) ou selecione um existente.

3. No menu lateral, acesse APIs e Serviços > Biblioteca.

4. Pesquise por Google Search Console API e clique em Ativar.

5. Acesse APIs e Serviços > Tela de consentimento OAuth:

   • Tipo de usuário: Externo.

   • Preencha o nome do app e emails de suporte.

   • Na etapa de Escopos, adicione: https://www.googleapis.com/auth/webmasters.readonly.

   • Na etapa de Usuários de teste, adicione o seu endereço de e-mail do Google (o mesmo que tem acesso ao Search Console).

6. Acesse APIs e Serviços > Credenciais > Criar Credenciais > ID do cliente OAuth:

   • Tipo de aplicativo: Aplicativo da Web ou App para computador.

   • Se for Aplicativo da Web, adicione https://developers.google.com/oauthplayground como URI de redirecionamento autorizada.

   • Anote o seu Client ID e Client Secret.

7. Gerando o Refresh Token via Google OAuth 2.0 Playground:

   • No canto superior direito, clique na engrenagem (⚙️) e marque Use your own OAuth credentials.

   • Insira o seu Client ID e Client Secret.

   • No campo Step 1, insira o escopo https://www.googleapis.com/auth/webmasters.readonly e clique em Authorize APIs.

   • Faça login com a sua conta Google e permita o acesso.

   • No Step 2, clique em Exchange authorization code for tokens.

   • Copie o valor do campo Refresh token.

Opção B: Service Account (Ideal para automações e servidores corporativos)

1. No console da GCP, acesse IAM e Administrador > Contas de Serviço.

2. Clique em Criar Conta de Serviço (ex: gsc-reader@seu-projeto.iam.gserviceaccount.com).

3. Clique na conta criada > aba Chaves > Adicionar Chave > Criar nova chave (JSON). O download do arquivo .json será feito.

4. Abra o Google Search Console.

5. Selecione o site desejado > Configurações > Usuários e permissões > Adicionar usuário.

6. Insira o e-mail da conta de serviço com a permissão Total ou Restrito (leitura).

🚀 Deploy Automatizado no Cloud Run

O repositório inclui scripts de automação completos que executam todas as etapas:

• Habilitação automática das APIs da Google Cloud.

• Criação e armazenamento seguro das credenciais no Secret Manager.

• Geração automática de uma chave segura MCP_API_KEY.

• Associação de permissões IAM para a conta de serviço do Cloud Run.

• Compilação e Deploy do serviço no Cloud Run.

• Emissão da URL final formatada para copiar e colar no seu cliente MCP.

No Windows (PowerShell):

.\setup_and_deploy.ps1

No Linux ou macOS (Bash):

chmod +x setup_and_deploy.sh
./setup_and_deploy.sh

Durante a execução interativa:

1. Digite o seu Project ID da GCP.

2. Escolha a região (padrão: us-central1 ou southamerica-east1 para São Paulo).

3. Selecione o método de autenticação (OAuth 2.0 ou Service Account).

4. Escolha gerar uma MCP_API_KEY segura automaticamente.

Ao término, o script exibirá o bloco de configuração JSON pronto para uso!

🔌 Como Conectar aos Clientes MCP

1. Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione a configuração do servidor SSE remoto:

{
  "mcpServers": {
    "gsc-cloud-run": {
      "url": "https://SEU-SERVICO-XYZ.a.run.app/sse?apiKey=SUA_MCP_API_KEY"
    }
  }
}

Reinicie o aplicativo do Claude Desktop. O ícone de martelo (Ferramentas) exibirá as 3 ferramentas do Google Search Console disponíveis.

2. Claude Web

Para conectar no Claude via navegador:

1. Acesse as configurações de ferramentas / conectores MCP da sua organização ou espaço de trabalho.

2. Adicione um novo servidor remoto informando a URL do seu endpoint:

   https://SEU-SERVICO-XYZ.a.run.app/sse?apiKey=SUA_MCP_API_KEY

3. Cursor IDE

No Cursor, você pode configurar o servidor MCP nas configurações:

1. Abra as Configurações do Cursor (Ctrl + , ou Cmd + ,).

2. Acesse a aba Features > MCP Servers.

3. Clique em + Add New MCP Server:

   • Type: sse

   • Name: gsc-cloud-run

   • URL: https://SEU-SERVICO-XYZ.a.run.app/sse?apiKey=SUA_MCP_API_KEY

4. Google Antigravity

Adicione ao arquivo mcp_config.json do seu projeto ou ambiente:

{
  "mcpServers": {
    "gsc-cloud-run": {
      "url": "https://SEU-SERVICO-XYZ.a.run.app/sse?apiKey=SUA_MCP_API_KEY"
    }
  }
}

💡 Exemplos Práticos de Prompts para SEO

Após conectar o servidor ao seu cliente favorito, você pode usar comandos como:

1. Descoberta de Oportunidades de CTR

"Analise o site https://meusite.com.br entre 2026-08-01 e 2026-08-31. Liste as 20 consultas com maior número de impressões que estejam entre a posição 4 e 10, e calcule quais têm o menor CTR. Dê recomendações de otimização de title tag para elas."

2. Diagnóstico de Canibalização de Palavras-Chave

"Consulte o Search Console para a query 'comprar tênis de corrida' no meu site no último mês, agrupando por página. Verifique se há múltiplas URLs disputando cliques e impressões para este mesmo termo."

3. Auditoria de Indexação em Tempo Real

"Inspecione o status da URL https://meusite.com.br/meu-novo-artigo no Search Console e me diga se ela está indexada, qual a canônica declarada pelo usuário e se o Google selecionou a mesma canônica."

4. Comparativo de Desempenho por Dispositivo

"Puxe as métricas de cliques e CTR do último trimestre agrupadas pela dimensão device e compare a taxa de conversão orgânica mobile versus desktop."

💻 Desenvolvimento Local

Para testar o servidor localmente no seu computador:

1. Clone o repositório:

   git clone https://github.com/SEU_USUARIO/gsc-mcp-server.git
   cd gsc-mcp-server

2. Instale as dependências:

   npm install

3. Crie o seu arquivo .env a partir do modelo:

   cp .env.example .env

4. Preencha as credenciais no .env.

5. Inicie o servidor em modo de desenvolvimento:

   npm run dev

6. O endpoint estará ouvindo em http://localhost:8080/sse.

🛡 Segurança

• Zero-Trust: Nenhuma credencial é gravada em repositório ou imagem Docker.

• Para reportar problemas ou vulnerabilidades de segurança, consulte nossa Política de Segurança.

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.