# gsc-mcp

MCP server que expõe a [Google Search Console API](https://developers.google.com/webmaster-tools) como ferramentas para qualquer cliente MCP-compatível (Claude Desktop, Cursor, etc.).

Permite que modelos de linguagem consultem dados de SEO, inspecionem URLs, gerenciem sitemaps e analisem performance de busca diretamente via linguagem natural.

---

## Ferramentas disponíveis

| Ferramenta | Descrição |
|---|---|
| `list_sites` | Lista todos os sites e propriedades verificadas na conta |
| `get_performance` | Busca dados de Search Analytics (cliques, impressões, CTR, posição média) com suporte a dimensões e filtros |
| `inspect_url` | Inspeciona uma URL: cobertura de índice, canonicals, status de rastreamento, AMP e usabilidade mobile |
| `list_sitemaps` | Lista todos os sitemaps enviados a uma propriedade |
| `submit_sitemap` | Envia ou atualiza um sitemap no Search Console |

### Detalhes de `get_performance`

Dimensões suportadas: `date`, `query`, `page`, `country`, `device`, `searchAppearance`

Parâmetros opcionais:
- `rowLimit` — número de linhas (1–25.000, padrão: 100)
- `startRow` — offset para paginação (padrão: 0)

---

## Pré-requisitos

- [Bun](https://bun.sh) >= 1.0
- Conta no Google Cloud Platform
- Propriedade verificada no Google Search Console

---

## Configuração do Google Cloud

### 1. Criar um projeto no GCP

1. Acesse o [Google Cloud Console](https://console.cloud.google.com/)
2. Clique em **Select a project → New Project**
3. Dê um nome (ex: `gsc-mcp`) e clique em **Create**

### 2. Ativar as APIs necessárias

Dentro do projeto criado, ative as duas APIs abaixo:

**Google Search Console API**
- Acesse: APIs & Services → Library
- Pesquise por `Google Search Console API`
- Clique em **Enable**

**Web Search Indexing API** (necessária para URL Inspection)
- Pesquise por `Web Search Indexing API`
- Clique em **Enable**

Ou use o link direto (substitua `SEU_PROJETO` pelo ID do projeto):
```
https://console.cloud.google.com/apis/library?project=SEU_PROJETO
```

### 3. Criar uma Service Account

1. Acesse: **IAM & Admin → Service Accounts**
2. Clique em **Create Service Account**
3. Preencha:
   - **Name**: `gsc-mcp` (ou qualquer nome descritivo)
   - **Description**: opcional
4. Clique em **Create and Continue**
5. Em "Grant this service account access to project", pode pular — clique em **Continue** e depois **Done**

### 4. Gerar a chave JSON

1. Na lista de Service Accounts, clique na conta recém-criada
2. Vá na aba **Keys**
3. Clique em **Add Key → Create new key**
4. Selecione **JSON** e clique em **Create**
5. O arquivo `.json` será baixado automaticamente — **guarde-o com segurança**

O arquivo tem este formato:
```json
{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
  "client_email": "gsc-mcp@SEU_PROJETO.iam.gserviceaccount.com",
  ...
}
```

Anote o valor de `client_email` — você vai precisar dele no próximo passo.

### 5. Conceder acesso no Google Search Console

A Service Account precisa ser adicionada como usuária da propriedade no GSC:

1. Acesse o [Google Search Console](https://search.google.com/search-console)
2. Selecione a propriedade desejada
3. No menu lateral, vá em **Configurações → Usuários e permissões**
4. Clique em **Adicionar usuário**
5. Cole o `client_email` da Service Account (ex: `gsc-mcp@SEU_PROJETO.iam.gserviceaccount.com`)
6. Selecione a permissão **Proprietário completo** (necessário para URL Inspection e envio de sitemaps)
7. Clique em **Adicionar**

> **Permissão mínima por funcionalidade:**
> - `list_sites`, `get_performance`, `list_sitemaps` → **Leitor**
> - `inspect_url`, `submit_sitemap` → **Proprietário completo**

---

## Instalação

```bash
git clone https://github.com/seu-usuario/gsc-mcp.git
cd gsc-mcp
bun install
bun run build
```

---

## Configuração da variável de ambiente

Há três formas de fornecer as credenciais (em ordem de prioridade):

### Opção A — JSON inline via variável de ambiente (recomendado para MCP config)

Converta o conteúdo do arquivo JSON para uma string. No terminal:

```bash
cat /caminho/para/chave.json | tr -d '\n'
```

Copie o resultado e defina como valor da variável `GOOGLE_SERVICE_ACCOUNT_KEY`.

### Opção B — Caminho para o arquivo JSON

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/caminho/para/chave.json"
```

### Opção C — Application Default Credentials (ADC)

```bash
gcloud auth application-default login
```

---

## Integração com Claude Desktop

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

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/caminho/absoluto/para/gsc-mcp/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"...\"}"
      }
    }
  }
}
```

> Substitua o valor de `GOOGLE_SERVICE_ACCOUNT_KEY` pelo JSON da chave em uma única linha (sem quebras de linha).

Reinicie o Claude Desktop após salvar.

---

## Integração com Cursor

Adicione ao `~/.cursor/mcp.json` (ou nas configurações do projeto em `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/caminho/absoluto/para/gsc-mcp/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"...\"}"
      }
    }
  }
}
```

---

## Exemplos de uso

Com o servidor configurado, você pode interagir via linguagem natural:

```
Liste todos os meus sites no Search Console.

Quais foram as 20 queries com mais cliques no site https://example.com/ nos últimos 30 dias?

Mostre a performance por página do site sc-domain:example.com entre 2025-01-01 e 2025-01-31, ordenado por impressões.

Inspecione a URL https://example.com/artigo-importante/ e me diga se está indexada.

Liste os sitemaps do site https://example.com/ e verifique se há erros.

Envie o sitemap https://example.com/sitemap.xml para a propriedade https://example.com/.
```

---

## Desenvolvimento

```bash
bun run dev    # executa direto via tsx (sem build)
bun run build  # compila para dist/
```

---

## Dependências principais

| Pacote | Versão | Uso |
|---|---|---|
| `@modelcontextprotocol/sdk` | ^1.28.0 | Protocolo MCP |
| `googleapis` | ^171.0.0 | Google Search Console API |
| `google-auth-library` | ^10.6.0 | Autenticação via Service Account |
| `zod` | ^4.0.0 | Validação de parâmetros |

---

## Licença

MIT