mcp-seo-audit

mcp-seo-audit

Un servidor local de Model Context Protocol para auditorías técnicas de SEO, renderizado de JavaScript, análisis de Search Console, comprobaciones de rendimiento y monitoreo recurrente. Sus 43 herramientas devuelven evidencia, URLs afectadas, correcciones sugeridas y límites de cobertura explícitos.

Versión actual del código fuente: 2.1.0. Instala este checkout para usar las funciones a continuación. Una actualización de GitHub no publica un paquete PyPI ni una versión en el MCP Registry; uvx mcp-seo-audit aún puede resolver una versión publicada anterior.

La implementación compatible es stdio para un usuario local de confianza, no un servicio alojado multi-tenant. Los rastreos de sitios públicos no requieren credenciales de Google. Basado en AminForou/mcp-gsc, con su atribución MIT preservada.

Instalación y conexión

Requiere Python 3.11 o posterior.

git clone https://github.com/GiorgiKemo/mcp-seo-audit.git
cd mcp-seo-audit
python -m venv .venv

Activa con .venv/Scripts/Activate.ps1 en Windows PowerShell o source .venv/bin/activate en macOS/Linux, luego instala las dependencias de ejecución fijadas y este paquete:

python -m pip install --require-hashes -r requirements.lock
python -m pip install --no-deps .

El lock incluye el paquete opcional de navegador Python. El renderizado de JavaScript también necesita Chromium:

python -m playwright install chromium

Para una instalación de código fuente más pequeña sin soporte de navegador, python -m pip install . resuelve rangos de dependencias principales en lugar del lock completo. Para agregar soporte de navegador más tarde, usa python -m pip install ".[browser]" e instala Chromium. Para desarrollo editable, usa python -m pip install -e ".[dev,browser]".

Linux puede requerir dependencias de navegador del sistema operativo; python -m playwright install --with-deps chromium las instala donde administras esos paquetes. El sandbox de Chromium permanece habilitado. Ejecuta como un usuario no root compatible con las facilidades del sistema operativo requeridas en lugar de deshabilitar el sandbox.

En Ubuntu 23.10+, una restricción de AppArmor de user-namespace puede causar el error No usable sandbox de Chromium. Pide al administrador de la máquina que siga las instrucciones de AppArmor por ejecutable de Chromium, permitiendo userns para las rutas exactas de los ejecutables de Chromium y headless-shell instalados. Mantén esos archivos de navegador confiables y actualiza el perfil después de las actualizaciones del navegador. El workflow de CI demuestra esta configuración limitada; conserva el sandbox de Chromium y la restricción a nivel de sistema.

Docker

Construye y conecta el contenedor stdio no root con un volumen con nombre para el historial de auditorías y la configuración:

docker build -t mcp-seo-audit:2.1.0 .
docker run --rm -i -v seo-audit-data:/data mcp-seo-audit:2.1.0

Configura el cliente MCP para lanzar el comando docker run. No se expone ningún puerto HTTP. La imagen admite rastreo crudo por defecto; incluye el paquete de navegador Python pero no el binario de Chromium ni las dependencias de navegador del sistema operativo. Las auditorías renderizadas requieren una configuración de imagen separada que instale ambos y admita el sandbox de navegador habilitado.

Ejecuta un lote de horarios explícitamente habilitados contra el mismo volumen de datos:

docker run --rm --entrypoint mcp-seo-monitor -v seo-audit-data:/data mcp-seo-audit:2.1.0 --once

Las credenciales de Google son opcionales para auditorías de sitios públicos. Para usar herramientas de Google, monta explícitamente tu propio archivo de credenciales en modo solo lectura y establece la variable de entorno de ruta de credenciales correspondiente; nunca copies credenciales dentro de la imagen. Consulta la configuración de autenticación a continuación.

Configuración del cliente MCP

Agrega un servidor stdio en la configuración de tu cliente MCP. Por ejemplo, en Windows:

{
  "mcpServers": {
    "seo-audit": {
      "command": "C:/path/to/mcp-seo-audit/.venv/Scripts/mcp-seo-audit.exe",
      "env": {
        "GSC_SKIP_OAUTH": "true",
        "SEO_AUDIT_ENABLE_WRITE_TOOLS": "false",
        "SEO_AUDIT_ALLOW_PRIVATE_URLS": "false"
      }
    }
  }
}

En macOS/Linux, usa la ruta absoluta a .venv/bin/mcp-seo-audit. Las ubicaciones de los archivos de configuración varían según el cliente. El proceso espera mensajes MCP en stdin; iniciarlo sin un cliente puede parecer que espera en silencio. get_server_status informa la configuración/disponibilidad local sin revelar credenciales ni probar el acceso a la cuenta de Google.

Acceso opcional a Google

• OAuth: habilita la API de Search Console en Google Cloud, crea una aplicación de escritorio OAuth y establece GSC_OAUTH_CLIENT_SECRETS_FILE a su JSON de cliente descargado. Establece GSC_SKIP_OAUTH=false. La primera operación de Google puede abrir el consentimiento del navegador. Habilita la API de Web Search Indexing si usas sus herramientas.
• Cuenta de servicio: establece GSC_CREDENTIALS_PATH al archivo de clave, otorga a la cuenta acceso a la propiedad relevante de Search Console y usa GSC_SKIP_OAUTH=true.
• APIs de rendimiento: establece CRUX_API_KEY para CrUX y opcionalmente PAGESPEED_API_KEY para PageSpeed Insights. GOOGLE_API_KEY es el respaldo de PageSpeed.

Mantén las credenciales fuera del checkout. Los tokens OAuth se guardan por defecto en el directorio de datos de usuario o en GSC_TOKEN_FILE. Los tokens heredados junto al servidor permanecen como respaldo de lectura durante la migración; la reautenticación fallida preserva el token funcional.

Las mutaciones de propiedades/sitemaps de Google y las llamadas de publicación de la API de Indexing requieren SEO_AUDIT_ENABLE_WRITE_TOOLS=true. Las herramientas locales de proyecto/historial no requieren esa marca de escritura de Google. La marca no reduce los alcances OAuth otorgados.

Auditar un sitio

Pregunta a tu cliente MCP:

Crea un informe SEO estructurado para https://example.com/ con hasta 25 páginas. Incluye descubrimiento de sitemap, compara HTML crudo y renderizado, y muestra brechas de cobertura antes de priorizar correcciones.

La herramienta subyacente acepta:

get_seo_audit_report(
  start_url="https://example.com/",
  max_pages=25,
  respect_robots=True,
  render_mode="compare",
  include_sitemaps=True,
  max_seconds=180
)

render_mode tiene como valor predeterminado raw; rendered analiza el DOM resultante, y compare también captura diferencias con el HTML devuelto por el servidor. Los informes directos tienen como valor predeterminado include_sitemaps=False. El presupuesto de tiempo de rastreo tiene un valor predeterminado de 180 segundos, configurable de 5 a 600. Los informes revelan cobertura parcial y razones de detención.

Los informes incluyen un esquema JSON versionado, marca de tiempo, IDs de reglas estables, severidad, evidencia, URLs afectadas, recomendaciones, observaciones de página y cobertura. Las comprobaciones cubren errores HTTP y fuentes de enlaces, metadatos, encabezados, indexabilidad, canónicos, títulos/descripciones duplicados, imágenes, enlaces, hreflang y perfiles JSON-LD seleccionados.

El descubrimiento de sitemaps sigue índices del mismo origen acotados y combina URLs de sitemap con descubrimiento de enlaces. Una URL de sitemap sin un enlace entrante observado es un candidato huérfano dentro de la muestra, no una prueba de que todo el sitio no tiene un enlace hacia ella.

Las comprobaciones de hreflang cubren la sintaxis de idioma/región y las auto-referencias observadas, enlaces de retorno, consistencia de clústeres y conflictos alternate/canonical. Los alternates no visitados o de origen cruzado permanecen sin verificar. Las comprobaciones de datos estructurados cubren campos básicos de Product, BreadcrumbList y la familia Article, revelando tipos/contextos no admitidos y referencias sin resolver. No certifican elegibilidad para rich results ni implementan todo el vocabulario de Schema.org.

Comparar correcciones

Llama a compare_seo_audits(baseline_json, current_json) con dos informes serializados usando la misma URL de inicio y configuración. Si tu cliente envuelve un informe bajo structuredContent.result, serializa el informe interno.

Resultado	Significado
new	Un hallazgo apareció con evidencia aplicable en ambas instantáneas.
resolved	Una re-comprobación aplicable exitosa verificó que el hallazgo desapareció.
persistent	El hallazgo permanece.
newly_observed	La línea base no cubrió la página o sus dependencias.
unverified	Una página o URL relacionada requerida no se re-comprobó exitosamente.

Las páginas faltantes nunca prueban correcciones. Una frontera de enlaces descubiertos completada nunca establece cobertura completa del sitio. Los hallazgos de recuento de palabras, longitud de título y metadatos sociales son guía de revisión, no requisitos de ranking.

Guardar proyectos y monitorear cambios

Crea un proyecto a través de MCP:

create_audit_project(
  project_id="example",
  start_url="https://example.com/",
  max_pages=25,
  render_mode="raw",
  include_sitemaps=True,
  retention=30
)
run_project_audit(project_id="example")

Los proyectos siempre respetan robots.txt y comienzan con la programación deshabilitada. Los IDs usan 1-64 letras minúsculas, dígitos, guiones o guiones bajos, comenzando con una letra o dígito. El ID de auditoría devuelto identifica una instantánea inmutable. Usa list_project_audits, get_project_audit y compare_project_audits para el historial. Las ejecuciones exitosas podan instantáneas antiguas según la retención configurada.

Opta por un horario diario:

set_audit_schedule(project_id="example", enabled=True, interval_seconds=86400)

Ejecuta el worker separado en el mismo entorno instalado, con la misma SEO_AUDIT_DATA_DIR y configuración de red:

mcp-seo-monitor

O procesa un lote acotado y sal, adecuado para un programador externo del sistema operativo:

mcp-seo-monitor --once

El servidor MCP nunca inicia un worker automáticamente. La primera ejecución programada vence un intervalo después de habilitarla. --once procesa como máximo 25 proyectos vencidos; repítelo o mantén el worker en ejecución para acumulaciones más grandes. El sondeo tiene un valor predeterminado de 30 segundos, configurable con --poll-seconds de 1 a 60. Ctrl+C cancela la auditoría activa y detiene el worker. Deshabilitar un horario evita futuras reclamaciones; una ejecución activa puede terminar.

Las bases de datos coordinan workers concurrentes mediante leases. Las ejecuciones tienen un tiempo de espera externo de diez minutos y un lease de once minutos para recuperación de fallos; el presupuesto de rastreo del informe puede detenerse antes. Los fallos usan retroceso exponencial con un tope de 24 horas, o el intervalo configurado cuando es más largo. Después de un fallo del proceso, otro worker puede reclamar el proyecto cuando expire su lease.

Lee list_audit_events(project_id="example", after_id=0) para cambios locales de hallazgos verificados, transiciones de fallos y recuperación. Guarda next_after_id y pásalo la próxima vez. Los hallazgos sin cambios y los cambios solo de muestreo permanecen silenciosos. No se envía ningún correo electrónico, webhook, notificación push u otro mensaje saliente.

Almacenamiento y retención

La base de datos es audits.sqlite3 bajo:

Plataforma	Directorio predeterminado
Windows	%LOCALAPPDATA%/mcp-seo-audit
macOS	~/Library/Application Support/mcp-seo-audit
Linux	$XDG_DATA_HOME/mcp-seo-audit, o ~/.local/share/mcp-seo-audit

Anula con SEO_AUDIT_DATA_DIR. Usa un sistema de archivos local con bloqueo SQLite confiable; no compartas una base de datos entre hosts ni la coloques en un sistema de archivos de red no confiable.

Límites: 100 proyectos, 1-100 instantáneas por proyecto (predeterminado 30), 10 MiB por instantánea y los últimos 500 eventos por proyecto. Los intervalos de horario son de 60 segundos a 31 días. Las marcas de tiempo de almacenamiento son segundos Unix UTC. La retención limita recuentos, no el uso global de disco; provisiona espacio en disco para tus tamaños de informe.

Los informes pueden contener metadatos de página, parámetros de URL y datos comerciales. El almacenamiento no está cifrado a nivel de aplicación. Para hacer una copia de seguridad, detén tanto el servidor como el monitor, luego copia de forma segura el directorio de datos incluidos los archivos sidecar de SQLite. Restaura con los procesos detenidos y conserva la copia de seguridad original hasta que se verifique. El directorio también puede contener tokens OAuth: trata las copias de seguridad como sensibles y nunca las adjuntes a problemas públicos.

Análisis y rendimiento

get_search_analytics_snapshot pagina con presupuestos explícitos de filas/requests/tiempo: predeterminado 25,000 filas, máximo 100,000 filas, como máximo 10 páginas de API dentro de 180 segundos. Las filas parciales sobreviven a fallos del proveedor. La cobertura incluye razón de detención, filas duplicadas y frescura; los recuentos de páginas de API excluyen intentos de reintento adicionales. Google aún limita los resultados a filas superiores seleccionadas, por lo que agotar una ventana de API no establece cobertura completa de tráfico. Referencia de consultas de Google.

prioritize_audit_issues ordena los hallazgos del informe por severidad, luego por clics/impresiones de página observados. La coincidencia de URL es exacta; las páginas no coincidentes son desconocidas, no tráfico cero. No predice ingresos ni ganancias de ranking.

Las llamadas de Google se ejecutan fuera del bucle de eventos a través de un worker serializado porque el transporte del cliente en caché no es seguro para subprocesos. Las lecturas reintentan errores seleccionados de límite de velocidad/servidor como máximo dos veces con retrasos acotados; las mutaciones se intentan una vez. La cancelación evita reintentos posteriores, pero una solicitud ya enviada a Google puede completarse.

CrUX informa datos de campo donde están disponibles; los resultados de PageSpeed/Lighthouse son mediciones de laboratorio. La falta de datos de campo no es una evaluación fallida de Core Web Vitals. Lighthouse local requiere un ejecutable de Lighthouse instalado, Chrome/Chromium y SEO_AUDIT_ENABLE_LOCAL_LIGHTHOUSE=true explícito. Las descargas a través de npx están deshabilitadas por defecto. El proceso separado de Chrome de Lighthouse no hereda la red protegida del rastreador renderizado; úsalo solo con objetivos confiables. Consulta SECURITY.md.

La API de Indexing admite páginas JobPosting elegibles y BroadcastEvent incrustadas en VideoObject. La aceptación de notificación no es prueba de indexación/eliminación; esta no es una API de indexación de propósito general para cada página. Guía de la API de Indexing de Google.

Referencia de herramientas

Área	Herramientas
Propiedades	list_properties, add_site, delete_site
Analítica de búsqueda	get_search_analytics, get_advanced_search_analytics, get_performance_overview, get_search_by_page_query, compare_search_periods, get_search_analytics_snapshot
Oportunidades de SEO	find_striking_distance_keywords, detect_cannibalization, split_branded_queries, prioritize_audit_issues
Inspección de URL	inspect_url, batch_inspect_urls
Notificaciones de indexación	request_indexing, request_removal, check_indexing_notification, batch_request_indexing
Sitemaps de Google	get_sitemaps, submit_sitemap, delete_sitemap
Rendimiento	get_core_web_vitals, get_pagespeed_insights, run_lighthouse_audit
Inspección en vivo	inspect_robots_txt, analyze_sitemap, analyze_page_seo, crawl_site_seo, audit_live_site
Informes estructurados	get_seo_audit_report, compare_seo_audits, site_audit
Proyectos y monitoreo	create_audit_project, list_audit_projects, set_audit_schedule, run_project_audit, list_project_audits, get_project_audit, compare_project_audits, list_audit_events
Autenticación y estado	reauthenticate, get_server_status

site_audit combina datos de la cuenta de Google. audit_live_site es un informe de texto del sitio en vivo. get_seo_audit_report es el flujo de trabajo estructurado de rastreo/comparación. Las descripciones de las herramientas exponen entradas y anotaciones de lectura/escritura a los clientes.

Configuración

Reinicie el servidor después de cambiar la configuración.

Variable	Predeterminado	Propósito
GSC_OAUTH_CLIENT_SECRETS_FILE	client_secrets.json junto al servidor	Archivo de cliente de escritorio OAuth; prefiera una ruta externa explícita.
GSC_CREDENTIALS_PATH	Ubicaciones convencionales de cuentas de servicio	Ruta JSON de la cuenta de servicio.
GSC_TOKEN_FILE	token.json en el directorio de datos del usuario	Destino del token; el token del paquete heredado es un respaldo de lectura.
GSC_SKIP_OAUTH	false	Omitir OAuth interactivo para herramientas de Google.
GSC_DATA_STATE	all	all incluye datos provisionales; final solicita datos finalizados.
CRUX_API_KEY	Vacío	Clave de API de CrUX.
PAGESPEED_API_KEY	GOOGLE_API_KEY o vacío	Clave de PageSpeed Insights.
GOOGLE_API_KEY	Vacío	Clave de PageSpeed de respaldo.
SEO_AUDIT_DATA_DIR	Directorio de datos del usuario de la plataforma	Almacenamiento de proyectos/historial y ubicación predeterminada del token.
SEO_AUDIT_BROWSER_PATH	Playwright Chromium	Ejecutable opcional de Chromium instalado para rastreo renderizado.
SEO_AUDIT_ENABLE_WRITE_TOOLS	false	Habilitar herramientas de Google que mutan.
SEO_AUDIT_ALLOW_PRIVATE_URLS	false	Permitir destinos privados solo para pruebas deliberadamente confiables.
SEO_AUDIT_MAX_FETCH_BYTES	5242880	Límite de bytes decodificados por respuesta; también limita las entradas directas de informes JSON.
SEO_AUDIT_MAX_REDIRECTS	5	Límite de redirecciones de recuperación HTTP.
SEO_AUDIT_MAX_SITEMAP_URLS	50000	Límite de URL para análisis de sitemaps individuales.
SEO_AUDIT_MAX_CRAWL_PAGES	100	Tope para intentos de páginas rastreadas.
SEO_AUDIT_ENABLE_LOCAL_LIGHTHOUSE	false	Permitir ejecución separada de Lighthouse para objetivos confiables.
LIGHTHOUSE_BINARY	Detección automática	Ruta del ejecutable de Lighthouse instalado.
LIGHTHOUSE_CHROME_PATH	CHROME_PATH o detección automática	Ruta de Chrome para Lighthouse local.
SEO_AUDIT_ALLOW_NPX_LIGHTHOUSE	false	Permitir descargar/ejecutar Lighthouse a través de npx.
LIGHTHOUSE_NO_SANDBOX	false	Anulación heredada de sandbox solo para Lighthouse; manténgalo deshabilitado normalmente.

Límites de rastreo y renderizado

• Los rastreos permanecen en el origen inicial, usan el agente de usuario mcp-seo-audit y conservan los parámetros de consulta/ruta. Googlebot puede recibir reglas diferentes.
• Los rastreos recursivos respetan robots.txt por defecto, incluyendo redirecciones y recursos renderizados. Las inspecciones de una sola página hacen solicitudes directas. Deshabilite robots solo para un sitio que usted controle.
• El análisis de robots está limitado a 500 KiB. Las páginas rastreadas se espacian al menos 0.2 segundos; se respeta un retraso de rastreo de hasta 10 segundos. Retrasos mayores y errores temporales de robots difieren el rastreo.
• Los presupuestos de páginas incluyen URL intentadas, errores y respuestas no HTML. El descubrimiento de sitemaps en informes se limita por separado a 10 documentos, 20 veces el presupuesto de páginas en candidatos, 5 MiB por documento decodificado y hasta 45 segundos dentro del presupuesto de rastreo restante.
• HTTP protegido valida todas las respuestas DNS y se conecta a una IP validada mientras preserva la verificación del nombre de host TLS. Los destinos privados, de bucle local, reservados y traducidos no seguros están bloqueados por defecto, incluyendo redirecciones.
• Las páginas renderizadas usan un contexto de Chromium nuevo en sandbox, recuperación de recursos GET/HEAD protegida, service workers/WebSockets/descargas bloqueados y sin sesión de navegador autenticada. Valores predeterminados: 30 segundos, 80 solicitudes, 20 MiB por página y un intervalo de asentamiento de 750 ms. Recursos bloqueados, errores de JavaScript o trabajo incompleto producen cobertura parcial. Los sitios que requieren inicio de sesión, escrituras, WebSockets o esperas más largas pueden renderizarse de forma incompleta.
• El contenido rastreado son datos no confiables. Los clientes no deben tratar el texto de la página, los metadatos o los hallazgos como permiso para ejecutar comandos o enviar mensajes.

Estos controles respaldan la auditoría local. No son autenticación, aislamiento de inquilinos ni un sustituto para la salida controlada de cargas de trabajo no confiables. Consulte SECURITY.md y la auditoría de implementación.

Desarrollo y verificación

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build
python -m pip_audit

Las pruebas aíslan credenciales y usan fixtures HTTP controlados y API de Google simuladas. CI está configurado para Windows/Linux y Python 3.11/3.13/3.14, con integración de navegador habilitada en Python 3.13 y una verificación separada de contenedor no root. Para integración local de navegador, instale Chromium y establezca SEO_AUDIT_TEST_BROWSER=1 antes de ejecutar pytest. Pasar pruebas fuera de línea no establece permisos en vivo de Google, cuotas, finalización remota de CI ni publicación de paquetes; la evidencia de lanzamiento pertenece a el registro de auditoría.

Consulte CONTRIBUTING.md para verificaciones de cambios/lanzamientos y CHANGELOG.md para cambios.

Licencia

MIT. Trabajo original con derechos de autor 2025 Amin Foroutan; contribuciones al proyecto con derechos de autor 2025-2026 GiorgiKemo.