gsc-mcp

gsc-mcp

MCP server que expõe a Google Search Console API 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 >= 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
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

1. Clique em Create and Continue
2. 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
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

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:

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

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

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

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

{
  "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):

{
  "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

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