Auditor SEO con Claude API: el script open-source que usamos con clientes

En SprintMarkt las auditorías web son parte del día a día: son la base de nuestra herramienta de auditoría SEO gratuita y de la prospección de clientes. Hacer una auditoría manual completa = 2-3 horas por web, sumando inspección, PageSpeed, Search Console, schema validator y comparativa de competidores. Con IA en el pipeline, el grueso de ese trabajo se automatiza — y el output es objetivamente más consistente, porque Claude no se cansa en la auditoría número 18.

Este post comparte la arquitectura y el código (Python, 350 líneas) que ejecutamos por cliente. Es código real, no demos teóricas. Cuesta ~0,06€ por auditoría en tokens de Claude API. Self-hosteable en cualquier VPS de 5€/mes. Sin dependencia SaaS.

Por qué Claude para auditar SEO (vs ChatGPT, vs herramientas tradicionales): ChatGPT con búsqueda web es bueno para queries puntuales pero no se le da bien analizar grandes bloques de HTML. Las herramientas tradicionales (Screaming Frog, Ahrefs Site Audit) son técnicamente exhaustivas pero te entregan 800 issues sin priorización ni contexto comercial. Claude 4.6 Sonnet es óptimo aquí por 3 razones: (1) ventana de contexto de 1M tokens — cabe la web entera sin trocear. (2) razonamiento sobre intent comercial — no te dice "tu meta description tiene 187 caracteres", te dice "tu página de servicios principal apunta a keyword informacional cuando debería ir a transaccional". (3) salida JSON estructurada con priorización por impacto/esfuerzo, no listado plano.

Arquitectura del script — pipeline 4 etapas: (1) SCRAPE — descarga HTML con Playwright (renderiza JS, ve lo que ve Google), extrae title, metas, schema markup, headings H1-H6, contenido principal, imágenes (alt + tamaño), enlaces internos/externos. (2) SEÑALES — combina con datos de PageSpeed Insights API (Core Web Vitals reales de campo), Search Console API si el cliente nos da acceso (queries con CTR<1%), Rich Results Test API (validez schema). (3) CLAUDE — un único prompt con todos los datos + instrucciones de priorización + few-shot examples de auditorías anteriores. Salida JSON estructurada con plan de acción. (4) RENDER — convierte el JSON a PDF con WeasyPrint o HTML con plantilla branded para el cliente.

Código completo (esqueleto) en Python: ```python

import anthropic, httpx, asyncio, json

from playwright.async_api import async_playwright

client = anthropic.Anthropic() # lee ANTHROPIC_API_KEY

PSI_KEY = os.environ['PAGESPEED_API_KEY']

async def fetch_rendered_html(url: str) -> dict:

async with async_playwright() as p:

browser = await p.chromium.launch()

page = await browser.new_page()

await page.goto(url, wait_until='networkidle')

html = await page.content()

title = await page.title()

meta_desc = await page.locator('meta[name=description]').get_attribute('content')

await browser.close()

return {'html': html, 'title': title, 'meta_desc': meta_desc}

async def fetch_psi(url: str) -> dict:

async with httpx.AsyncClient(timeout=60) as c:

r = await c.get(

'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',

params={'url': url, 'strategy': 'mobile', 'key': PSI_KEY}

)

return r.json()['lighthouseResult']

async def audit(url: str) -> dict:

page_data = await fetch_rendered_html(url)

psi_data = await fetch_psi(url)

prompt = f"""Audita esta página web y devuelve JSON con plan priorizado.

URL: {url}

TITLE: {page_data['title']}

META: {page_data['meta_desc']}

LCP: {psi_data['audits']['largest-contentful-paint']['displayValue']}

CLS: {psi_data['audits']['cumulative-layout-shift']['displayValue']}

HTML (recortado): {page_data['html'][:30000]}

Devuelve JSON con esta estructura:

{{

"overall_score": 0-100,

"top_issues": [{{ "priority": 1-5, "title": "", "impact": "alto|medio|bajo", "effort": "horas|días|semanas", "explanation": "" }}],

"plan_30_60_90": {{ "days30": [], "days60": [], "days90": [] }}

}}"""

response = client.messages.create(

model='claude-sonnet-4-6',

max_tokens=4000,

messages=[{'role': 'user', 'content': prompt}]

)

return json.loads(response.content[0].text)

```

El prompt es el 80% del trabajo — el código es trivial, lo que diferencia el output de Claude es CÓMO le pides el análisis. Cosas que mejoran muchísimo el resultado: (1) Few-shot examples reales de 3-4 auditorías anteriores con su output esperado — Claude aprende tu estilo. (2) Instrucciones explícitas de priorización: "si una página tiene LCP > 4s en móvil, eso es siempre P1 sobre cualquier otro issue". (3) Limitar el ámbito: "no analices CSS ni JavaScript, solo señales SEO observables por Googlebot". (4) Pedirle salida en JSON estructurada con campos obligatorios — evita texto suelto. (5) Sufijo del prompt "si no estás seguro de un dato, marca confidence:low" — Claude deja de inventar.

Coste real por auditoría en tokens (precios Claude Sonnet 4.6 mayo 2026): input ~30K tokens (HTML recortado + PSI + Search Console) = 0,045€. Output ~3K tokens (JSON plan) = 0,015€. Total ~0,06€. PageSpeed Insights API es gratuita (25K queries/día). Playwright self-hosted gratuito. Si lo monetizas como producto a 49€/auditoría, margen brutal. Si lo usas internamente, cada auditoría pasa de 2-3 horas de trabajo senior a minutos de revisión del informe.

Cómo lo integro en el dashboard de cliente: el script se dispara desde el panel del cliente (Next.js + Supabase). El cliente pega la URL, le da a "Auditar". El backend FastAPI recibe la petición, lanza el pipeline asyncio, va emitiendo eventos ("scrape ok", "psi ok", "claude pensando...") por WebSocket. Cuando termina, guarda el JSON en Supabase y envía email al cliente con link al informe HTML. El cliente puede pedir refinamientos en lenguaje natural: "explícame más el punto 3", "dame el plan en sprints de 2 semanas", "¿cuánto costaría implementarlo todo?". Cada refinamiento es 0,01-0,03€ adicional.

El mejor caso de prueba: nuestra propia web. Antes de apuntar el script a nadie, lo apuntamos a sprintmarkt.com — y encontró cosas que llevaban meses delante de nuestras narices: un vídeo de fondo de 23,6MB cargándose en una sección de la home, otro vídeo del hero de 3,3MB que se descargaba DOS veces por un preload mal configurado, logos de clientes que pesaban 756KB en total para mostrarse a 45px de alto, y un H1 con animación de opacidad que retrasaba artificialmente el texto principal casi 2 segundos. Todo verificado con PageSpeed, todo corregido el mismo día. Moraleja doble: (1) el auditor automático ve lo que el ojo acostumbrado ya no ve, y (2) si un auditor no es capaz de encontrar fallos en la web de su propio autor, desconfía de él.

¿Quieres el script o una adaptación a tu stack? El esqueleto completo está en este post (Playwright + PageSpeed + Claude); si quieres la versión completa con el wrapper FastAPI y la plantilla HTML del informe, o que lo adaptemos a tu caso, escríbenos desde la página de contacto. Y si solo quieres ver el resultado sin montar nada: nuestra herramienta de auditoría SEO gratuita de la web usa exactamente este enfoque.