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

En SprintMarkt auditamos 30-50 webs al mes para clientes potenciales y proyectos activos. Hacerlo manual = 2-3 horas por web, sumando inspección, PageSpeed, Search Console, schema validator, comparativa competidores. Antes de meter IA gastábamos 80h/mes solo en auditorías. Hoy gastamos 12h/mes y el output es objetivamente mejor — 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 como lo hacemos en SprintMarkt, te ahorras 60h/mes de tiempo senior — esos son los números reales.

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.

3 casos reales con output del script (anonimizado): caso A — e-commerce cosmética 250 SKUs: Claude detectó que 137 fichas de producto tenían el mismo meta description copiado, lo que diluía completamente el ranking. Plan: regenerar metas con script Claude usando el nombre + 3 propiedades de cada producto. ROI medido: +24% impresiones en 6 semanas. Caso B — landing legal-tech con LCP 5.1s: Claude identificó que el hero usaba un video MP4 de 18MB sin lazy, sumado a 4 fuentes web cargadas. Plan: vídeo a Cloudflare Stream con poster WebP + variable font subseted. LCP a 1.3s en 1 sprint. Caso C — blog inmobiliario 80 posts: Claude detectó que 23 posts apuntaban a la misma keyword (canibalización SEO) y propuso plan de fusión/redirect que recuperó tráfico de 5 posts que se canibalizaban entre ellos.

Repositorio GitHub público: subiremos el script completo (con Playwright, PageSpeed, Claude integration, FastAPI wrapper, template HTML del informe) en github.com/sprintmarkt/seo-auditor-claude bajo licencia MIT en las próximas semanas. Si quieres acceso anticipado o adaptación a tu stack, escríbenos. La intención es que cualquier agencia o freelance pueda usarlo sin pagar SaaS de auditoría, y que se mejore comunitariamente.