@justmpm/search-console

MCP Server para Google Search Console focado em analise de dados de desempenho, indexacao e sitemaps.

Fluxo recomendado: analisar dados agregados primeiro e investigar URLs uma por vez com url_inspect.

Instalação

npm install @justmpm/search-console

Configuração

1. Criar Credenciais OAuth no Google Cloud Console

1. Acesse Google Cloud Console
2. Crie um novo projeto ou selecione um existente
3. Habilite a Search Console API em "Library"
4. Vá em "Credentials" > "Create Credentials" > "OAuth client ID"
5. Selecione "Web application"
6. Adicione authorized redirect URI: http://localhost:3000/callback
7. Copie o Client ID e Client Secret

2. Salvar Credenciais

Crie o arquivo de credenciais:

mkdir -p ~/.search-console
echo '{"client_id":"SEU_CLIENT_ID","client_secret":"SEU_CLIENT_SECRET","redirect_uri":"http://localhost:3000/callback"}' > ~/.search-console/credentials.json

3. Autorizar Acesso

Execute o fluxo de autorização OAuth:

npx @justmpm/search-console auth

Isso vai:

• Abrir o browser para você autorizar
• Receber o callback em servidor local
• Salvar os tokens em ~/.search-console/tokens.json

Uso como MCP

Adicione ao seu arquivo de configuração MCP:

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["@justmpm/search-console"]
    }
  }
}

Tools Disponíveis

search_analytics

Consulta dados de desempenho do Search Console.

Parâmetros:

• siteUrl (obrigatório): URL da propriedade
• startDate (obrigatório): Data inicial (YYYY-MM-DD)
• endDate (obrigatório): Data final (YYYY-MM-DD)
• dimensions: Agrupar por (date, query, page, country, device, searchAppearance)
• type: Tipo de busca (web, image, video, news, discover)
• device: Filtrar por dispositivo (DESKTOP, MOBILE, TABLET)
• country: Filtrar por país (código ISO 3166-1 alpha-3)
• rowLimit: Máximo de linhas (1-25000)

Exemplo:

{
  "siteUrl": "https://example.com/",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": ["query", "page"],
  "rowLimit": 100
}

url_inspect

Verifica status de indexação de uma URL específica.

Parâmetros:

• inspectionUrl (obrigatório): URL a inspecionar
• siteUrl (obrigatório): URL da propriedade

Retorna:

• Status de indexação (indexada/não indexada)
• Motivos de não indexação
• Último crawl
• URL canônica do Google
• Rich Results detectados

sitemap_audit

Auditoria de indexação focada em analise (sem operacoes de escrita e sem inspeção em lote).

Parâmetros:

• siteUrl (obrigatório): URL da propriedade
• sitemapUrl (obrigatório): URL do sitemap XML
• listLimit: Quantidade máxima de URLs para listar (1-200, padrão: 50)

Retorna:

• Taxa de indexação agregada do sitemap
• Erros e warnings do processamento
• Lista de URLs do sitemap para investigar com url_inspect

list_sites

Lista todas as propriedades do Search Console.

list_sitemaps

Lista sitemaps enviados para uma propriedade.

Parâmetros:

• siteUrl (obrigatório): URL da propriedade

Fluxo Recomendado para IA

1. list_sites para descobrir o siteUrl correto
2. list_sitemaps para descobrir o sitemapUrl correto
3. sitemap_audit para resumo + lista de URLs
4. url_inspect para investigar cada URL importante
5. search_analytics para priorizar páginas com impacto

Casos de Uso

"Quais páginas têm mais tráfego?"

{
  "name": "search_analytics",
  "arguments": {
    "siteUrl": "https://example.com/",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "dimensions": ["page"],
    "rowLimit": 20
  }
}

"Essa URL está indexada?"

{
  "name": "url_inspect",
  "arguments": {
    "siteUrl": "https://example.com/",
    "inspectionUrl": "https://example.com/minha-pagina"
  }
}

"Qual a taxa de indexação do meu sitemap?"

{
  "name": "sitemap_audit",
  "arguments": {
    "siteUrl": "https://example.com/",
    "sitemapUrl": "https://example.com/sitemap.xml",
    "listLimit": 100
  }
}

"Desempenho mobile no Brasil"

{
  "name": "search_analytics",
  "arguments": {
    "siteUrl": "https://example.com/",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "dimensions": ["query"],
    "device": "MOBILE",
    "country": "BRA"
  }
}

Limitações

• URL Inspection API: Rate limit de ~2 requisições/segundo
• Search Analytics: Máximo 25.000 linhas por requisição
• Sitemap Audit: Lista até 200 URLs por execução

Troubleshooting

"Credenciais OAuth não configuradas"

Execute o setup de credenciais:

npx @justmpm/search-console auth --setup

"Token expirado"

Os tokens são renovados automaticamente. Se houver problemas, re-autentique:

rm ~/.search-console/tokens.json
npx @justmpm/search-console auth

"URL não encontrada"

Verifique se a URL está registrada exatamente como no Search Console:

• https://example.com/ (com barra final)
• sc-domain:example.com (para domain properties)

"Insufficient Permission" / 403

• Confirme que a conta autenticada tem acesso a propriedade
• Rode list_sites para validar se o site aparece para essa conta

"API has not been used" / API desabilitada

• Habilite a Search Console API no projeto OAuth
• Aguarde 2-5 minutos e tente novamente

Desenvolvimento

# Instalar dependências
npm install

# Build
npm run build

# Desenvolvimento
npm run dev

# Testar autenticação
npm run auth

Licença

MIT © Koda AI Studio