SEO MCP

Servidor MCP para evidências de SEO — auditoria on-page, rastreamento, GSC, PageSpeed, SERP opcional

Documentação

mcp-server-seo

Servidor MCP em Rust para evidências de SEO usado por Grok Build e Claude Code: auditoria on-page, robots/sitemap, crawl educado, PageSpeed Insights, Google Search Console, SERP pago opcional.

stdio + JSON-RPC via rmcp. Sem Docker.

Dois binários compartilham o mesmo mecanismo:

Binário	Função
`seo`	CLI headless (`doctor`, `tool`, `audit daily\|weekly`, `mail`)
`mcp-server-seo`	Servidor MCP stdio para agentes de IA

Compilação

cargo build --release
install -Dm755 target/release/seo ~/.local/bin/seo
install -Dm755 target/release/mcp-server-seo ~/.local/bin/mcp-servers/mcp-server-seo

Cron / SeoAuditBot usa seo. Agentes continuam usando mcp-server-seo.

Configuração

Opcional: ~/.config/mcp-server-seo/config.toml (veja config.example.toml).

mkdir -p ~/.config/mcp-server-seo
cp config.example.toml ~/.config/mcp-server-seo/config.toml
chmod 600 ~/.config/mcp-server-seo/config.toml

As ferramentas da Fase 1 funcionam com zero chaves. O GSC precisa de um JSON de conta de serviço; o PageSpeed precisa de uma chave de API gratuita; o SERP precisa de Serper (opcional).

Ferramentas (resumo)

Grupo	Ferramentas
Fundação	`status`, `sites_list`, `site_resolve`
On-page	`page_audit` (`mode=quick\|full`, `target_keyword`), `page_text`, `redirect_trace`, `robots_check`, `sitemap_*`, `extract_structured_data`, `schema_validate`, `link_check`, `entity_coverage`
Crawl / grafo	`crawl_run` (retomável, `seed_sitemap`), `crawl_report`, `crawl_results`, `crawl_diff`, `sitemap_coverage`, `sitemap_build`, `internal_link_graph` (órfãos verdadeiros)
Local / arquitetura	`url_architecture_plan`, `nap_consistency` (schema-first), `citation_prospects`, `gbp_audit`, `gbp_reviews_snapshot`, `local_audit`
Conteúdo / KW	`content_brief` (fundamentado em SERP), `keyword_research` (ranqueado), `keyword_volumes`, `keyword_intent`, `keyword_suggest`
Autoridade	`authority_snapshot` (grátis, Open PageRank), `backlink_overview` (pago, com portão)
Performance	`pagespeed_audit`
GSC	`gsc_`, `gsc_opportunities`, `gsc_trends`, `log_event`*
SERP / rank	`serp_fetch` (`num`, pacote local), `rank_history` (série), `rank_watch`
Compostos	`page_snapshot`, `page_history`, `audit_page`, `audit_site`, `verify_live`, `rank_diagnosis`
Loop de correção	`findings_list`, `findings_diff` (padrão: duas últimas execuções), `url_to_source`

Roteiro recomendado de agente gratuito-primeiro (v0.7)

page_audit mode=full (+ target_keyword) na página inicial + modelos principais
page_text em qualquer página cujo conteúdo você precise avaliar — a auditoria retorna contagens, isso retorna as seções reais
crawl_run com seed_sitemap=true → internal_link_graph; se coverage.truncated, chame novamente com resume_crawl_id até a fronteira esgotar, então leia true_orphans
local_audit para NAP/GBP/autoridade/avaliações em uma única passada
authority_snapshot antes de concluir que uma página limpa "só precisa de mais on-page" — um veredito de déficit significa links, não polimento
serp_fetch uma vez por consulta alvo (~$0,001, confirm=YES-PAY) → content_brief lê o SERP armazenado para perguntas PAA e H2s apoiados por concorrentes
rank_diagnosis quando uma palavra-chave específica tem desempenho inferior — classifica indexação vs relevância vs autoridade vs técnico
verify_live após o deploy, então log_event para que o movimento tenha uma causa associada
Próxima sessão: findings_diff (sem ids de execução) — fixed vs new/regressed. url_to_source mapeia uma URL para o arquivo sob [[sites]].source_root

Loop semanal (agende a partir do seu cliente MCP — este servidor não executa daemon)

gsc_trends site=<property> refresh=true      # stores today's snapshot, returns movers
rank_watch action=run confirm=YES-PAY        # re-checks tracked queries

Leia movers_up / movers_down ao lado do events que você registrou.

Novo site, sem histórico de GSC (~$0,10)

keyword_research seed=<service> geo=<city> mode=all
keyword_volumes keywords=[...] confirm=YES-PAY        # one call, cached 90 days
serp_fetch <top terms> confirm=YES-PAY                # unlocks difficulty + SERP clustering
keyword_research ...                                  # now returns a ranked shortlist
url_architecture_plan / content_brief                 # human approval before publish

A publicação de conteúdo permanece no CMS — este servidor é evidências + briefings, não um redator.

Segurança

SSRF: apenas http(s) público; IPv4+IPv6 privados/reservados bloqueados; saltos de redirecionamento re-verificados
sitemap_build: grava apenas sob storage.data_dir (out_path relativo)
Envio GSC: confirm=YES-SUBMIT (API de sitemaps — não Inspeção de URL)
SERP pago: dry_run=true padrão; confirm=YES-PAY + registro de orçamento
Autoridade paga (backlink_overview): mesmo portão, registro de orçamento separado [authority]; a execução seca faz zero chamadas ao provedor e o registro anota o custo real reportado pelo provedor
HTML estático: rendered: false — use agent-browser para JS

Chaves opcionais (v0.7)

Chave	Desbloqueia	Custo
`authority.open_pagerank_api_key`	`authority_snapshot`, etapa de autoridade em `local_audit`, vereditos `rank_diagnosis`, dificuldade de palavra-chave	grátis (domcop)
`authority.dataforseo_login` / `_password`	lacuna de links `backlink_overview`, `keyword_volumes`	pague conforme o uso, com limite de orçamento
`serp.api_key`	`serp_fetch` / `rank_watch` → fundamenta `content_brief`, dificuldade de palavra-chave, verificações de presença de citação	~$0,001/consulta
`local.places_api_key`	classificação `gbp_reviews_snapshot`, velocidade de avaliações, lacuna de concorrentes	camada gratuita + limite mensal de chamadas
`gsc.credentials_file`	`gsc_*` incl. histórico `gsc_trends` e `gsc_opportunities`	grátis

Verifique antes de confiar nos números: o custo de crédito do seu provedor de SERP para num > 10 (serp.num_100_multiplier), o keywords.location_code do DataForSEO para o seu país e o preço atual dos campos da API Places. Todos os três são valores de configuração, não codificados.

Não reimplemente

Use MCPs irmãos: google-analytics, google-adwords, cloudflare, namecheap, agent-browser.

Clientes

Já registrado como seo no Grok Build / Claude Code (reinicie os clientes após recompilar).

Testes

cargo test --release
./tests/test-stdio.sh

Plano

Veja PLAN.md (fusão de Grok + Fable + Kimi + emendas de crítica).

Layout do módulo (v0.7)

src/
  bin/seo.rs        # CLI (doctor, tool, audit daily|weekly, mail)
  bin/mcp_server_seo.rs
  server/           # thin MCP tool-router only (no SEO logic)
    params.rs       # all tool input schemas
    dispatch/       # named-tool router + one exec file per handler group
    playbooks.rs    # daily/weekly audits; ok=false on step errors
    mod.rs          # SeoServer, shared helpers, chained tool_router()
    handlers/       # #[tool] wrappers → run_named; one sub-router per file
                    #   (site, page, crawl, pagespeed, gsc, serp, audit,
                    #    findings, content, authority, local)
  tools/            # business logic per concern
    page/           # parse, og probe, structured data, text extraction, audit
    crawl/          # BFS crawl + report builder
    local/          # nap, citations, gbp, local_audit
    gsc/            # client (JWT) + ops (analytics/inspect/sitemaps)
    authority/      # open pagerank (free) + dataforseo (paid) adapters
    audit/          # composites: page, site, verify_live, rank_diagnosis
    source_map.rs   # URL → repo file (convention presets, sandbox)
    serp_evidence.rs# stored-SERP parser shared by briefs/keywords
    html_dom.rs     # shared HTML extract helpers incl. main-text extraction
    …
  rules/            # pure rules (checklist, schema, patterns, intent, relevance, issue)
  storage/          # SQLite split by domain (crawls, snapshots, spend, authority,
                    #   keywords, gsc, rank, places, events,
                    #   findings/{persist,extract,query,family}) over one shared conn
  http.rs / config.rs / site.rs / util.rs

Regra: sem arquivos Deus — a lógica vive sob tools/* / rules/*; server/ não implementa algoritmos de SEO. Construtores de problemas compartilhados vivem em rules/issue.rs.