aeos-seo-mcp

MCP server em Node.js que expõe Google Search Console + Google Analytics 4 + Chrome UX Report + Indexing API + auditoria on-page + AEO/GEO + inteligência de priorização como tools para agentes especialistas em SEO. Invocado via npx -y aeos-seo-mcp dentro do Claude Code, opencode, Cursor ou qualquer cliente MCP.

O que você ganha

61 tools MCP organizadas em blocos:

Google APIs (17)

• GSC primitivas (5): gsc_list_sites, gsc_search_analytics, gsc_url_inspect, gsc_list_sitemaps, gsc_get_sitemap
• GSC write actions (4): gsc_submit_sitemap, gsc_delete_sitemap, gsc_add_site, gsc_remove_site
• GA4 primitivas (4): ga4_run_report, ga4_run_realtime, ga4_batch_run_reports, ga4_list_metadata
• CrUX (1): crux_query
• Indexing API (3): indexing_publish_url, indexing_batch_publish, indexing_get_notification_status

Composições SEO baseadas em GSC/GA4 (18)

seo_find_keyword_opportunities, seo_content_decay_report, seo_striking_distance, seo_keyword_cannibalization, seo_ranking_changes, seo_ctr_anomalies, seo_branded_vs_nonbranded, seo_landing_page_performance, seo_query_intent_clusters, seo_technical_health, seo_search_appearance_breakdown, seo_diff_analyses, seo_index_coverage_audit, seo_attribution_comparison, seo_derive_ctr_curve, seo_realtime_spike_detection, seo_audience_overlap, seo_international_split

Otimização de conteúdo & workflows de indexação (5)

seo_title_meta_suggestions, seo_content_brief, seo_internal_linking_opportunities, seo_submit_unindexed_urls, seo_resubmit_sitemaps

On-page técnica URL-a-URL (10 — novos v0.2.0)

• seo_onpage_audit — score 0-100 + issues priorizados (title, meta, headings, canonical, hreflang, robots, OG, Twitter, imagens sem alt, schema, keyword focus)
• seo_pagespeed_insights — Lighthouse mobile/desktop via PageSpeed API (grátis): scores + CWV lab + LCP element + oportunidades + diagnostics
• seo_structured_data_audit — JSON-LD + Microdata + RDFa; valida 18 tipos schema.org contra Rich Result requirements
• seo_robots_audit — parse + audit de /robots.txt, testa paths para user-agents
• seo_sitemap_deep_validator — estrutura, lastmod/priority/changefreq, amostra URLs via HEAD para detectar 404s
• seo_hreflang_validator — extrai HTML + header HTTP Link; valida reciprocidade buscando cada alternativa
• seo_redirect_chain — segue redirects, detecta loops, cross-host, mixed protocol, 302 abusivo
• seo_canonical_consistency — cruza HTML canonical × URL efetiva × GSC userCanonical/googleCanonical
• seo_content_quality — Flesch pt/en, densidade keyword, top keywords, bigrams, headings-to-word ratio
• seo_alerts_config + seo_alerts_check — thresholds persistentes (queda de rank/clicks/CTR, CWV regression)

AEO / GEO — SEO para Answer Engines (6 — novos v0.2.0)

• aeo_content_chunk_analysis — Q&A pairs, TL;DR, direct answer nos primeiros 300 chars, listicles, tables, definitions
• aeo_faq_extractor — extrai Q&A do HTML e gera JSON-LD FAQPage pronto para colar
• aeo_llms_txt_generator — gera /llms.txt a partir de sitemap ou URLs, agrupado em seções
• aeo_entity_presence — checa presença no Wikidata (QID, P856) + Wikipedia por idioma
• aeo_ai_overview_readiness — score 0-100 composto (chunks + schema + FAQ + freshness + direct answer)
• aeo_citation_watchlist — CRUD manual de citações em Perplexity/ChatGPT Search/Copilot/Gemini/Kagi/etc.

Inteligência & priorização (4 — novos v0.2.0)

• seo_action_prioritizer — normaliza findings de N tools → ranking ICE/RICE com cumPct
• seo_wayback_diff — diff estrutural URL atual vs. snapshot Internet Archive (grátis)
• seo_competitive_gap — compara sua URL com 1-5 concorrentes (word count, schemas, keywords, bigrams)
• seo_llm_recommendation_synth — consolida saídas em relatório + prompt executivo pt-BR para o LLM cliente sintetizar

Renderizador de relatórios

seo_render_report — 19 templates markdown pt-BR (monthly_audit_narrative, opportunities, decay, cannibalization, striking_distance, cwv, index_coverage, sitemap_management, custom, etc.).

Infra

• SQLite cache com TTL por tipo + snapshots históricos (trend YoY funciona).
• Alertas persistentes e watchlist de citações AEO em tabelas dedicadas.
• OAuth2 com refresh token (setup one-time). Scopes read-only por default; write scopes só para indexing/sitemaps.

Requisitos

• Node.js ≥ 22.5 (usa node:sqlite nativo).
• Um projeto no Google Cloud com Search Console API e Google Analytics Data API habilitadas.
• OAuth client tipo Web com redirect URI http://localhost:8765/oauth/callback.
• (opcional) API key do Chrome UX Report para crux_query e CWV em seo_technical_health.
• (opcional) API key do PageSpeed Insights para elevar quota de seo_pagespeed_insights (funciona sem key com quota reduzida).

Instalação e autorização

npm install -g aeos-seo-mcp      # ou use npx
aeos-seo-mcp setup               # OAuth flow (uma vez por máquina)

O setup vai:

1. Pedir client_id / client_secret (ou ler de SEO_MCP_CLIENT_ID / SEO_MCP_CLIENT_SECRET).
2. Imprimir uma URL de autorização — abra no navegador.
3. Capturar o redirect em http://localhost:8765/oauth/callback.
4. Salvar ~/.seo-mcp/credentials.json (mode 0600) com o refresh token.

A conta Google autorizada precisa ter acesso às properties GSC e GA4 que você quer consultar.

Configuração do cliente MCP

Claude Code (.mcp.json ou ~/.claude.json)

{
  "mcpServers": {
    "aeos-seo-mcp": {
      "command": "npx",
      "args": ["-y", "aeos-seo-mcp"],
      "env": {
        "SEO_MCP_DEFAULT_PROPERTY_GSC": "sc-domain:example.com",
        "SEO_MCP_DEFAULT_PROPERTY_GA4": "123456789",
        "SEO_MCP_CRUX_API_KEY": "AIza...",
        "SEO_MCP_PSI_API_KEY": "AIza..."
      }
    }
  }
}

opencode (.opencode/opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "seo-mcp": {
      "type": "local",
      "command": ["npx", "-y", "aeos-seo-mcp"],
      "enabled": true
    }
  }
}

Variáveis de ambiente

| Env var | Default | Uso | |---|---|---| | SEO_MCP_CREDENTIALS_PATH | ~/.seo-mcp/credentials.json | Arquivo OAuth | | SEO_MCP_CACHE_PATH | ~/.seo-mcp/cache.db | SQLite cache + snapshots + alerts + citations | | SEO_MCP_CACHE_DISABLE | unset | 1 desliga cache (debug) | | SEO_MCP_DEFAULT_PROPERTY_GSC | unset | siteUrl default (evita passar em toda chamada) | | SEO_MCP_DEFAULT_PROPERTY_GA4 | unset | GA4 property id default | | SEO_MCP_CRUX_API_KEY | unset | Chrome UX Report API key. Sem ela, crux_query retorna { noData: true, reason: "no_api_key" } | | SEO_MCP_PSI_API_KEY | unset | PageSpeed Insights API key. Sem ela, quota reduzida mas funciona |

Como o agente SEO usa

System prompt sugerido:

Você é um analista SEO especialista para Cliente X. O MCP aeos-seo-mcp expõe Search Console, GA4, CrUX, Indexing, auditoria on-page URL-a-URL, AEO/GEO e priorização ICE/RICE. Sempre confirme o siteUrl com gsc_list_sites. Prefira composições de alto nível. Para auditoria de página crítica, encadeie: seo_onpage_audit → seo_structured_data_audit → seo_pagespeed_insights → seo_canonical_consistency → aeo_ai_overview_readiness → seo_action_prioritizer → seo_render_report.

Exemplos de prompts que funcionam end-to-end:

GSC/GA4 clássico

• "Liste minhas properties GSC."
• "Encontre 25 oportunidades de keyword no domínio X."
• "Detecte páginas com queda de tráfego nos últimos 28 dias e gere o relatório."
• "Cruze landing pages do GSC com engagement e conversões do GA4 do último mês."

On-page & técnico

• "Audite https://example.com/produto-x: title, meta, schema, canonical, CWV."
• "Rode Lighthouse mobile e desktop para essa URL e me diga as 3 maiores oportunidades."
• "Valide o hreflang dessa URL — está recíproco?"
• "Meu robots.txt está bloqueando algum asset crítico?"

AEO / GEO

• "Essa página está pronta para AI Overview e Perplexity? Score composto + gaps."
• "Extraia FAQ da minha página e me dê o JSON-LD FAQPage."
• "Gere um /llms.txt a partir do meu sitemap."
• "Minha marca aparece no Wikidata? Se sim, o website oficial está correto?"

Inteligência

• "Consolide todos esses findings em plano de ação priorizado por ICE."
• "Como estava minha página há 6 meses (Wayback)? Perdi conteúdo?"
• "Compare minha URL com essas 3 concorrentes: quais schemas e sub-tópicos me faltam?"

Cache

TTLs default (desligue via SEO_MCP_CACHE_DISABLE=1):

| Tipo | TTL | |---|---| | html_fetch (páginas raspadas) | 30 min | | GSC search analytics / URL inspect / sitemaps | 6h | | GSC list sites | 24h | | GA4 reports | 1h | | GA4 realtime | 30s | | GA4 metadata | 24h | | PageSpeed Insights | 6h | | CrUX | herda do withCache do endpoint | | Wikidata search / entity | 24h | | Wayback available | 24h | | Indexing status | 5 min |

Snapshots diários são gravados automaticamente por seo_ranking_changes (top 1000 queries) — comparações YoY continuam funcionando meses depois.

Desenvolvimento local

npm install
npm test                                       # 97 testes com node:test
node bin/aeos-seo-mcp.js setup                 # OAuth flow
node bin/aeos-seo-mcp.js                       # servidor stdio (JSON-RPC)

Aponte um cliente MCP para um checkout local:

{ "command": "node", "args": ["/abs/path/to/SEO-MCP/bin/aeos-seo-mcp.js"] }

Layout do projeto

bin/aeos-seo-mcp.js                  # CLI: setup vs server
src/index.js                         # MCP server, registra as 61 tools, stdio transport
src/auth/                            # OAuth2 client + fluxo de setup interativo
src/google/                          # Wrappers googleapis: searchConsole, analytics, indexingApi
src/cache/                           # SQLite (db, apiCache TTL, snapshots)
src/lib/
  ├── seoHeuristics.js               # CTR curve, opportunity scoring, decay, intent
  ├── crux.js, sitemapFetch.js       # Clientes CrUX + fetch de sitemap
  ├── htmlFetch.js, htmlParse.js     # Fetch com cache + parser Cheerio (v0.2.0)
  ├── pageSpeedApi.js                # Cliente PageSpeed Insights API v5 (v0.2.0)
  ├── schemaValidator.js             # Validador schema.org (18 tipos Rich Results) (v0.2.0)
  ├── robotsParse.js                 # Parser + matcher robots.txt (v0.2.0)
  ├── readability.js                 # Flesch pt/en, stopwords, bigrams (v0.2.0)
  ├── aeoSignals.js                  # Q&A, TL;DR, direct answers, listicles (v0.2.0)
  ├── wikidata.js                    # Cliente Wikidata + Wikipedia (v0.2.0)
  ├── waybackApi.js                  # Cliente Internet Archive (v0.2.0)
  ├── prioritizer.js                 # ICE/RICE scoring + category inference (v0.2.0)
  ├── analysisDiff.js                # Diff estruturado de análises
  ├── confirmationGuard.js           # confirm: true em write actions
  ├── errors.js, markdown.js         # AuthError/QuotaError; helpers pt-BR
src/tools/
  ├── gsc.js, ga4.js                 # Primitivas Google
  ├── crux.js                        # crux_query
  ├── compositions.js                # 18 composições GSC/GA4
  ├── actions.js                     # GSC write actions (submit/delete/add/remove)
  ├── indexing.js                    # Indexing API tools
  ├── contentOptimization.js         # title/meta suggestions, briefs, internal linking
  ├── reports.js                     # seo_render_report + 19 templates
  ├── onpage/                        # v0.2.0 — 10 tools on-page
  │     audit.js, pagespeed.js, structuredData.js, robots.js,
  │     sitemapDeep.js, hreflang.js, redirect.js, canonical.js,
  │     contentQuality.js, alerts.js
  ├── aeo/                           # v0.2.0 — 6 tools AEO/GEO
  │     chunkAnalysis.js, faqExtractor.js, llmsTxtGenerator.js,
  │     entityPresence.js, aiOverviewReadiness.js, citationWatchlist.js
  └── intelligence/                  # v0.2.0 — 4 tools de priorização/comp
        actionPrioritizer.js, waybackDiff.js, competitiveGap.js, llmSynth.js
tests/                               # 97 testes com node:test
skills/aeos-seo-mcp/SKILL.md         # Manual operacional completo (v0.6.0)

Escopo e limites

• Zero dependência paga. Todas as fontes externas são gratuitas: Google APIs (GSC/GA4/CrUX/Indexing/PageSpeed), Wikidata, Wikipedia, Internet Archive. Cheerio é a única dependência de parsing.
• Análise on-page URL-a-URL sob demanda — sem crawler massivo (por design). Cada tool on-page espera URL específica.
• Read-first, write-with-confirmation. Todas as write actions (gsc_submit_sitemap, gsc_add_site, indexing_publish_url, seo_submit_unindexed_urls, etc.) exigem confirm: true como parâmetro; gsc_remove_site exige dupla confirmação (confirmDeletion: "YES_DELETE_PROPERTY").
• Single account per machine: um credentials file por SEO_MCP_CREDENTIALS_PATH. Rode entradas MCP separadas com paths diferentes para múltiplos clientes de agência.
• Watchlist AEO é manual: o MCP não raspa Perplexity/ChatGPT Search (TOS). O usuário roda a consulta e cola o resultado via aeo_citation_watchlist { action: "record" }.
• CTR curve é industry-aggregate por default; use seo_derive_ctr_curve para calibrar por nicho.

Manual operacional detalhado

Veja skills/aeos-seo-mcp/SKILL.md — manual completo com semântica de datas, catálogo de todas as 61 tools com signatures, heurísticas explicadas, 15 workflows prontos, tratamento de erros e pitfalls.

Licença

MIT.