SEO Webmaster MCP

Audita una web desde tu asistente con solo pegar su URL. Este MCP local y de solo lectura detecta problemas técnicos y propone acciones con evidencia y pasos de verificación. Puedes conectar Google Search Console y Bing Webmaster Tools para añadir datos oficiales. Requiere Node.js 22 o posterior.

Pega una URL → encuentra problemas concretos → corrígelos → repite la auditoría para verificar el cambio.

Guía paso a paso, con un caso real de CTR bajo: Cómo auditar el SEO de tu web con tu asistente de IA y Search Console.

Inicio rápido

No necesitas clonar ni compilar el repositorio, ni configurar credenciales para tu primera auditoría. Conecta tu cliente MCP:

npx -y seo-webmaster-mcp inicia el servidor por stdio. Ejecuta npx -y seo-webmaster-mcp config codex|claude|cursor para copiar la configuración correspondiente; no incluyas claves en ella.

Codex:

codex mcp add seo-webmaster -- npx -y seo-webmaster-mcp
codex mcp list

Claude Desktop: agrega lo siguiente a claude_desktop_config.json y reinicia la aplicación. Cursor: agrega el mismo objeto a tu mcp.json.

{
  "mcpServers": {
    "seo-webmaster": {
      "command": "npx",
      "args": ["-y", "seo-webmaster-mcp"]
    }
  }
}

Consulta la configuración MCP de Codex, la ayuda de Claude Desktop o la documentación MCP de Cursor si tu cliente requiere una ruta distinta. En Windows, si el cliente no encuentra npx, usa la ruta absoluta del ejecutable npx.cmd.

Tu primera auditoría

Pide a tu asistente:

Audita https://example.com con seo_audit_advanced. Prioriza los problemas detectados y muestra las URL afectadas, la evidencia, cómo corregirlos y cómo comprobar cada corrección. Distingue los problemas confirmados de las comprobaciones que requieren contexto.

La llamada mínima es:

{ "baseUrl": "https://example.com/" }

El informe puede detectar errores HTTP, enlaces internos rotos, títulos ausentes o repetidos, canónicas mal formadas y directivas de indexación. También propone revisar imágenes sin alt, idioma de la página y viewport. Analiza el HTML recibido sin ejecutar JavaScript y no confirma la indexación real. Los apartados de datos oficiales quedan vacíos hasta que indiques una propiedad de Google o Bing.

summary indica cuántas páginas HTML se analizaron, qué se comprobó, qué quedó pendiente y si el rastreo se limitó. actions: [] significa que no se detectaron problemas en esas comprobaciones y esa muestra; no equivale a una auditoría exhaustiva ni garantiza que no haya nada que mejorar.

summary.truncationReasons explica los límites alcanzados: max_pages (URL pendientes), discovery_limit (hasta 2 × maxPages URL distintas descubiertas) o sitemap_limit (hasta seis archivos de sitemap). Los enlaces repetidos y fragmentos como #seccion no consumen páginas adicionales. Las canónicas y enlaces relativos se resuelven usando el primer <base href> cuando existe.

Cada página incluye jsonLdBlocks, con los bloques application/ld+json numerados desde 1. parsed indica JSON legible con raíz de objeto o array de objetos; invalid_json identifica JSON mal formado o vacío, y invalid_root una raíz incompatible. Los errores generan la acción invalid_json_ld con URL, bloque y pasos de corrección. Esta comprobación no resuelve contextos remotos ni valida la semántica de schema.org o los requisitos de resultados enriquecidos; completa esa revisión con Rich Results Test. Los indicadores indexablePages y snippetEligiblePages son señales del HTML observado, no confirmación de indexación o elegibilidad real.

Para una comprobación rápida de una sola página, añade "maxPages": 1. Por defecto rastrea hasta 100 páginas.

Nuevas comprobaciones de HTML en 0.4.0

| Acción | Qué observa | Cómo interpretarla | | --- | --- | --- | | images_missing_alt | Imágenes del body sin atributo alt. | Revisar cada imagen: texto descriptivo si informa o alt="" si es decorativa. La auditoría acepta alt vacío y no evalúa la calidad del texto. | | missing_lang | <html lang> ausente o vacío. | Declarar el idioma real para ayudar a lectores de pantalla y otras tecnologías de asistencia; no representa una penalización SEO medida. | | missing_viewport | Meta viewport ausente o con contenido vacío en el head. | Revisar la configuración móvil. La presencia de la etiqueta no demuestra que el diseño funcione en móvil. | | invalid_canonical | El href de la canónica no resuelve a una URL HTTP(S) válida. | Corregir el valor y comprobar que corresponda a la versión elegida. El resto del análisis de la página se conserva. |

Las tres primeras acciones tienen prioridad baja y confidence: "inferred": la evidencia es la ausencia observada y la corrección necesita contexto. Cada acción contiene URL, evidencia, pasos y verificación. Se cuentan todas las páginas afectadas y se muestran hasta veinte URL de ejemplo.

Cada página incorpora lang y viewport (valor observado o null), canonicalError (null o el motivo del error) e images:

{
  "total": 2,
  "missingAlt": 1,
  "examples": [{ "imageIndex": 1, "src": "./audit-flow.svg" }]
}

imageIndex es la posición de la imagen entre los img del body, desde 1. examples incluye hasta cinco imágenes sin alt por página; src conserva el atributo recibido, recortado a 300 caracteres, o null si falta. No se descargan imágenes ni se añaden peticiones para estas comprobaciones. No es una auditoría completa de accesibilidad.

Las señales noindex y snippetBlocked combinan las etiquetas generales robots, todas las etiquetas googlebot y las reglas HTTP aplicables a Googlebot. Reconocen none como noindex, nofollow y no atribuyen a Google las reglas dirigidas exclusivamente a otro agente. Son señales para Google, no una simulación de todos los buscadores. Una canónica inválida deja canonical: null y genera invalid_canonical, sin duplicar missing_canonical ni convertir el HTTP 200 en un error de conexión.

Demostración: detectar, corregir y verificar

Desde un checkout del repositorio, después de npm ci, ejecuta:

npm run demo

La demo ejecuta dos llamadas reales al MCP con DNS y HTTP simulados, sin salir a internet ni consultar credenciales. Usa los archivos originales before.html y after.html:

| Ejecución | Resultado esperado | | --- | --- | | Antes | invalid_canonical, images_missing_alt, missing_lang y missing_viewport. HTTP 200 conservado. | | Después | Desaparecen las cuatro acciones; dos imágenes tienen alt, incluida una decorativa con alt="". |

Se imprimen la cobertura, los datos de la página y la evidencia completa de las acciones. audit.example es un destino ficticio de la demo. Para repetirla contra una web, sirve los archivos en una URL pública propia o autorizada y audita cada URL con maxPages: 1; adapta la canónica de after.html si cambias su ruta. La ausencia de acciones en esta muestra no garantiza indexación ni posiciones.

En una web propia o autorizada, usa una página de prueba pública sin <title>. Audítala con maxPages: 1: la acción missing_title incluirá su URL y el número de páginas afectadas. Añade un título descriptivo, publica la corrección y repite la misma auditoría: esa acción debería desaparecer. Puedes mostrar ambas ejecuciones para documentar la mejora; el cambio no garantiza resultados de posicionamiento.

También puedes reproducir un error de JSON-LD con <script type="application/ld+json">{"@type":"Organization",}</script>: la coma final genera invalid_json_ld. Al quitarla y repetir la auditoría, ese bloque debería aparecer como parsed y la acción desaparecer.

¿Te ayudó a encontrar algo que corregiste? ¿Dónde te atascaste? Cuéntalo en una issue, indicando tu cliente MCP, sistema operativo y pasos para reproducirlo. Anonimiza los datos privados y evita incluir credenciales.

Guardar y comparar auditorías (0.5.0)

Puedes completar el ciclo desde la CLI, sin clonar el repositorio:

npx -y seo-webmaster-mcp@0.5.0 audit https://example.com/ --max-pages 25 --save
npx -y seo-webmaster-mcp@0.5.0 history
npx -y seo-webmaster-mcp@0.5.0 report ID --format markdown --out informe.md
# Tras corregir y publicar tu web, repite audit con --save:
npx -y seo-webmaster-mcp@0.5.0 compare ID_BASE ID_ACTUAL --format markdown

--save guarda explícitamente un informe en el perfil local y devuelve saved.id. Sin esa opción no se crea historial. La comparación distingue hallazgos nuevos, persistentes, resueltos y no comparables: omitir una página o fallar al comprobarla nunca cuenta como corrección. --out exporta JSON o Markdown sin sobrescribir archivos existentes.

Desde MCP puedes usar seo_audit_save, seo_audit_history, seo_audit_report y seo_audit_compare. De las 29 herramientas, 28 declaran lectura; seo_audit_save declara escritura local no idempotente. Ninguna modifica la web.

La versión nueva añade módulos aislados con cobertura y revisiones de hreflang, canonical múltiples/destinos, coherencia del sitemap, encabezados, tarjetas sociales y propiedades de tipos schema.org seleccionados, incluidos @graph. --render js activa un Chrome/Chromium/Edge instalado y --performance consulta PageSpeed Insights; ambos son opcionales. No es una validación semántica completa.

npx -y seo-webmaster-mcp@0.5.0 audit https://example.com/ --render js --max-pages 5 --save
npx -y seo-webmaster-mcp@0.5.0 audit https://example.com/ --performance --performance-strategy mobile

Consulta uso, herramientas y límites, la evidencia de verificación y la hoja de ruta.

Añadir Google o Bing (opcional)

Configura cada proveedor que quieras usar:

npx -y seo-webmaster-mcp setup bing
npx -y seo-webmaster-mcp setup google --client /ruta/al/cliente-oauth.json
npx -y seo-webmaster-mcp status
npx -y seo-webmaster-mcp doctor

Bing: crea tu clave en Bing Webmaster Tools. El asistente la solicita sin mostrarla y comprueba que funciona.

--help muestra los comandos y --version la versión instalada. doctor devuelve código de salida 1 si falla un proveedor configurado; sin proveedores devuelve not_configured y código 0.

Google: en Google Cloud Console habilita la Search Console API, configura la pantalla OAuth y descarga un cliente OAuth de tipo Desktop app. Si la aplicación está en modo Testing, agrega tu cuenta como usuario de prueba. Pasa el archivo JSON al comando setup google; el navegador solicitará acceso de solo lectura y completará la conexión mediante un callback local. Cada usuario crea su propio cliente OAuth; no compartas el JSON ni el token de renovación. Guía oficial de autorización.

La configuración se guarda fuera del repositorio, en el perfil del usuario. status muestra la ruta y el estado sin revelar secretos; doctor prueba el acceso real a ambos proveedores. Para desconectar: npx -y seo-webmaster-mcp disconnect google o disconnect bing. En macOS/Linux el a