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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/Protocol-MCP%201.0-purple.svg)](https://modelcontextprotocol.io/)
[![Google Cloud Run](https://img.shields.io/badge/Deploy-Google%20Cloud%20Run-4285F4?logo=googlecloud&logoColor=white)](https://cloud.google.com/run)

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](#-recursos-e-ferramentas-disponíveis)
- [Arquitetura e Segurança DevSecOps](#-arquitetura-e-segurança-devsecops)
- [Pré-requisitos](#-pré-requisitos)
- [Passo a Passo: Obtenção de Credenciais no Google](#-passo-a-passo-obtenção-de-credenciais-no-google)
- [Deploy Automatizado no Cloud Run](#-deploy-automatizado-no-cloud-run)
- [Como Conectar aos Clientes MCP](#-como-conectar-aos-clientes-mcp)
  - [Claude Desktop](#1-claude-desktop)
  - [Claude Web](#2-claude-web)
  - [Cursor IDE](#3-cursor-ide)
  - [Google Antigravity](#4-google-antigravity)
- [Exemplos Práticos de Prompts para SEO](#-exemplos-práticos-de-prompts-para-seo)
- [Desenvolvimento Local](#-desenvolvimento-local)
- [Segurança](#-segurança)
- [Licença](#-licença)

---

## 🛠 Recursos e Ferramentas Disponíveis

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

| Ferramenta | Descrição | Parâmetros Principais |
| :--- | :--- | :--- |
| `gsc_list_sites` | Lista todas as propriedades verificadas que o usuário tem acesso no Search Console. | *(Nenhum)* |
| `gsc_query_analytics` | Consulta métricas detalhadas de tráfego orgânico (cliques, impressões, CTR e posição média). Permite quebrar por dimensões (`query`, `page`, `country`, `device`, `date`, `searchAppearance`) e filtrar termos. | `siteUrl`, `startDate`, `endDate`, `dimensions`, `filters`, `rowLimit`, `searchType` |
| `gsc_inspect_url` | Inspeciona em tempo real o status de rastreamento, canônica e indexação de uma URL específica na propriedade. | `siteUrl`, `inspectionUrl`, `languageCode` |

---

## 🏗 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](https://search.google.com/search-console).
3. **Google Cloud SDK (`gcloud` CLI)** instalado na sua máquina ([Instruções de instalação](https://cloud.google.com/sdk/docs/install)).
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](https://console.cloud.google.com/).
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](https://developers.google.com/oauthplayground):
   - 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](https://search.google.com/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):
```powershell
.\setup_and_deploy.ps1
```

### No Linux ou macOS (Bash):
```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:

```json
{
  "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:

```json
{
  "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:
   ```bash
   git clone https://github.com/SEU_USUARIO/gsc-mcp-server.git
   cd gsc-mcp-server
   ```
2. Instale as dependências:
   ```bash
   npm install
   ```
3. Crie o seu arquivo `.env` a partir do modelo:
   ```bash
   cp .env.example .env
   ```
4. Preencha as credenciais no `.env`.
5. Inicie o servidor em modo de desenvolvimento:
   ```bash
   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](SECURITY.md).

---

## 📄 Licença

Distribuído sob a licença **MIT**. Veja [`LICENSE`](LICENSE) para mais informações.