seo-audit-mcp

Un servidor MCP que le da a Claude (o a cualquier cliente MCP) la capacidad de auditar el SEO técnico de un sitio web en vivo: cobertura del mapa del sitio, problemas por página y cadenas de redirección.

Pide en lenguaje natural — "audita mortgagecalculatortools.com y dime de qué páginas Google nunca llega a enterarse" — y el modelo llama a las herramientas, rastrea el sitio y responde con detalles.

El problema que resuelve

El sitemap.xml de un sitio es cómo le dices a Google qué páginas existen. Cuando falta una página, nada da error y nada avisa: la página simplemente nunca acumula impresiones. Comprobarlo a mano significa comparar un listado del sistema de archivos con un archivo XML, así que en la práctica nadie lo hace.

Caso práctico: una brecha de 25 páginas que resultó ser correcta

El primer sitio al que se apuntó esto tenía 125 archivos HTML en disco y 100 URL en su mapa del sitio. Una brecha de 25 páginas — el tipo de hallazgo que se reporta como un bug y se asigna a alguien.

Una llamada a sitemap_coverage sacó a la luz la brecha, y una llamada a audit_urls sobre una muestra la explicó: cada una de las 25 llevaba <meta name="robots" content="noindex, follow">. Eran dos clústeres de contenido deliberadamente desindexados, y el mapa del sitio tenía toda la razón al omitirlos. Verificado después contra el sistema de archivos: 25 páginas noindex en disco, las mismas 25 ausentes del mapa del sitio, cero páginas noindex incluidas por error. Consistencia perfecta.

Ese es el resultado útil. Un número de cobertura a secas ("125 vs 100") se lee como un defecto y se lleva un día del tiempo de alguien; cobertura más el estado noindex por página cierra la cuestión en un minuto. Esta herramienta es tan valiosa por las falsas alarmas que elimina como por las brechas reales que encuentra — por eso audit_urls informa del noindex por página en lugar de limitarse a contar URL.

Herramientas

Cada herramienta devuelve JSON estructurado con una lista issues por página y un issue_summary agregado, de modo que el modelo pueda razonar sobre los recuentos en lugar de releer el HTML en bruto.

Instalación

pip install -e .

Requiere Python 3.10+. Dependencias: mcp>=2.0.0, httpx.

Conéctalo a Claude Code

Añádelo a .mcp.json en tu proyecto (o ~/.claude.json para uso global):

{
  "mcpServers": {
    "seo-audit": {
      "command": "python",
      "args": ["-m", "seo_audit_mcp"]
    }
  }
}

Para Claude Desktop, el mismo bloque va en claude_desktop_config.json.

Entonces solo pregunta:

Obtén el mapa del sitio de https://example.com/sitemap.xml, audita las primeras 20 URL y resume los problemas por frecuencia.

Ejecútalo directamente

python -m seo_audit_mcp        # stdio transport

Notas de diseño

Tres decisiones que merece la pena destacar, porque son la diferencia entre una demo y algo a lo que puedes apuntar en el sitio de producción de un cliente:

El rastreo está limitado en velocidad por diseño. fetch_many se ejecuta detrás de un asyncio.Semaphore limitado a 16 solicitudes concurrentes, y cada herramienta limita su entrada. Un mapa del sitio de 500 URL sin ese límite abriría 500 sockets a la vez y se interpretaría como un ataque al host de destino. El rastreo es un coste que paga el sitio objetivo, por lo que el límite no se puede configurar al alza desde la superficie de la herramienta.

Ningún fallo de obtención aborta una ejecución. fetch_one captura httpx.HTTPError y lo registra en el PageAudit devuelto en lugar de lanzarlo. Un host muerto en un rastreo de 200 URL degrada una fila en lugar de perder 199 resultados buenos.

El análisis sintáctico es deliberadamente permisivo. El HTML del mundo real está malformado con la frecuencia suficiente como para que un analizador estricto que lance una excepción a mitad del rastreo sea un problema. Los extractores son regex permisivas que devuelven None en lugar de lanzar una excepción — pero con las trampas controladas: los cuerpos de <script> y <style> se eliminan antes de contar palabras y extraer encabezados, de modo que un <h1> dentro de un literal de cadena JS no se cuenta como encabezado, y los enlaces canónicos relativos se resuelven contra la URL de la página.

normalize_url deliberadamente no elimina las barras finales: /a y /a/ pueden ser páginas realmente distintas, y unificarlas ocultaría problemas de contenido duplicado que esta herramienta existe para sacar a la luz.

Pruebas

pip install -e ".[dev]"
pytest

El conjunto de pruebas no usa red — HTTP se ejercita a través de httpx.MockTransport, por lo que se ejecuta en CI y en un avión. Cubre los casos límite del análisis que muerden en producción: encabezados incrustados en scripts, sitemaps sin espacio de nombres, enlaces canónicos relativos, URL de sitemap que devuelven un HTML 404 estilizado con estado 200, y tipos de contenido no HTML que se informan erróneamente como páginas "sin título".

Licencia

MIT