Recursos // Open source
Cómo auditar el SEO de tu web con tu asistente de IA y Search Console.
Por Jude Hermoza · Publicado: 21 oct. 2026 · Lectura: 8 min
Construimos una herramienta de código abierto para revisar el SEO de nuestra propia web y la publicamos para que cualquiera la use. Esta guía te lleva de cero a tu primera auditoría, te enseña a conectar Search Console y muestra cómo la usamos para encontrar por qué nuestras mejores posiciones no recibían clics.
Respuesta directa
Un MCP es un conector que permite a tu asistente de IA (Codex, Claude Desktop, Cursor) usar herramientas externas. seo-webmaster-mcp es uno de solo lectura: con la URL pública de tu web audita errores técnicos sin ninguna credencial, y si conectas Google Search Console o Bing Webmaster Tools añade tus datos reales de clics, impresiones y posición. Se instala con un comando, requiere Node.js 22 o posterior y es gratuito bajo licencia MIT.
Qué hace y qué no toca.
Tiene 29 herramientas. Las que no necesitan cuentas rastrean tu sitio y revisan errores HTTP, enlaces internos rotos, títulos ausentes o repetidos, canónicas mal formadas, directivas de indexación, JSON-LD inválido, imágenes sin alt, idioma y viewport. Las que sí usan tus cuentas leen Search Console y Bing.
Es de solo lectura: 28 herramientas leen y una guarda un informe en tu equipo cuando tú lo pides. Ninguna cambia tu web, tu propiedad de Search Console ni tu cuenta de Bing. El rastreo respeta el robots.txt, solo visita URL públicas de tu mismo sitio y limita cada respuesta a 2 MB.
Paso 1. Conéctalo a tu asistente.
Necesitas Node.js 22 o posterior. No hace falta clonar el repositorio ni compilar nada: npx descarga y ejecuta el paquete publicado. Si usas Codex:
codex mcp add seo-webmaster -- npx -y seo-webmaster-mcp
codex mcp list
Para Claude Desktop o Cursor, agrega este objeto a claude_desktop_config.json o a tu mcp.json y reinicia la aplicación:
{
"mcpServers": {
"seo-webmaster": {
"command": "npx",
"args": ["-y", "seo-webmaster-mcp"]
}
}
}
Si no recuerdas el formato, npx -y seo-webmaster-mcp config claude (o codex, cursor) imprime la configuración lista para pegar, sin claves. En Windows, si tu cliente no encuentra npx, usa la ruta absoluta de npx.cmd.
Paso 2. Haz tu primera auditoría sin credenciales.
Pídele a tu asistente:
Audita https://tu-sitio.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.
Detrás, el asistente llama a seo_audit_advanced con una entrada mínima. Por defecto rastrea hasta 100 páginas; agrega "maxPages": 1 si solo quieres revisar una.
{ "baseUrl": "https://tu-sitio.com/" }
Cada acción del informe trae la URL afectada, la evidencia, los pasos para corregirla y cómo verificar el cambio. Lee tres cosas antes de actuar:
- El campo
summary dice cuántas páginas se analizaron y si el rastreo se cortó por algún límite. - Una lista de acciones vacía significa que esas comprobaciones no encontraron problemas en esa muestra. No es una garantía de que tu SEO esté bien.
- El análisis es del HTML recibido, sin ejecutar JavaScript. Si tu sitio se construye en el navegador, agrega la opción
--render js, que usa un Chrome, Chromium o Edge ya instalado.
Paso 3. Conecta Search Console y Bing.
Es opcional, pero aquí está lo más útil: tus consultas, clics y posiciones reales. Para Google necesitas un cliente OAuth propio, porque cada usuario crea el suyo:
- En Google Cloud Console, habilita la Search Console API.
- Configura la pantalla de consentimiento OAuth y, si está en modo Testing, agrega tu cuenta como usuario de prueba.
- Crea y descarga un cliente OAuth de tipo Desktop app.
- Pasa ese JSON al comando de configuración. El navegador te pide acceso de solo lectura.
npx -y seo-webmaster-mcp setup google --client /ruta/al/cliente-oauth.json
npx -y seo-webmaster-mcp setup bing
npx -y seo-webmaster-mcp status
npx -y seo-webmaster-mcp doctor
Para Bing, el asistente de configuración te pide la clave de API de Bing Webmaster Tools sin mostrarla. status muestra qué está conectado sin revelar secretos y doctor prueba el acceso real. Las credenciales quedan en el perfil de tu usuario, fuera de cualquier repositorio. No compartas el JSON del cliente ni el token de renovación.
Con las cuentas conectadas, la auditoría puede combinar el rastreo técnico con datos oficiales. Indica tu propiedad tal como aparece en Search Console, por ejemplo sc-domain:tu-sitio.com si es de dominio:
{
"gscSiteUrl": "sc-domain:tu-sitio.com",
"baseUrl": "https://www.tu-sitio.com/",
"maxPages": 100
}
Si omites las fechas, usa los últimos 90 días cerrados hasta tres días antes de la ejecución. Si un proveedor falla, el informe conserva lo demás y te muestra el error.
Paso 4. Encuentra dónde pierdes clics: un caso real.
La herramienta gsc_opportunities separa dos señales para investigar: consultas con CTR bajo dentro del top 10 y consultas en las posiciones 10 a 20. Son pistas, no errores oficiales. La corrimos sobre nuestra propia web, del 22 de septiembre al 19 de octubre de 2026:
| Consulta | Impresiones | Posición | Clics |
| software factory | 2,332 | 6.0 | 5 (0.2 %) |
| hermoza (marca) | 231 | 8.0 | 0 |
| ley 29733 | 90 | 4.3 | 0 |
La primera consulta era la anomalía: muchísimas impresiones, buena posición y casi ningún clic. Para entender por qué, usamos gsc_query_advanced con la dimensión país, filtrando las consultas que contienen "software factory". Perú aportó 339 impresiones y un clic; Chile 275, España 258 y Argentina 197, también con un clic cada uno. La mayoría de las impresiones venía de fuera de Perú y nuestro título decía "software factory en Perú"; es probable que quienes buscaban la definición del término no sintieran que la página era para ellos.
La respuesta fue cambiar el título para que empiece por la definición. Es una hipótesis, no un resultado: la muestra es pequeña, un CTR bajo en posición 6 también puede deberse a lo que Google muestra encima de los resultados, y aún no sabemos si el cambio funciona. La mediremos a las cuatro semanas con el mismo informe.
Lo valioso del flujo es que cada paso sale de datos y se puede repetir: detectar la anomalía con gsc_opportunities, abrirla por país, dispositivo o página con gsc_query_advanced o gsc_page_performance, cambiar una cosa y volver a medir.
Paso 5. Guarda la auditoría y compara después.
Corregir sin medir no demuestra nada. Desde la versión 0.5.0 puedes guardar auditorías y comparar dos de ellas:
npx -y seo-webmaster-mcp audit https://tu-sitio.com/ --max-pages 25 --save
npx -y seo-webmaster-mcp history
# publica tus correcciones y repite la auditoría con --save
npx -y seo-webmaster-mcp compare ID_BASE ID_ACTUAL --format markdown
La comparación clasifica los hallazgos como nuevos, persistentes, resueltos o no comparables. Omitir una página o fallar al revisarla nunca cuenta como una corrección, así que un informe "limpio" no se puede lograr dejando de mirar. Sin la opción --save no se guarda nada.
Lo que esta herramienta no te dice.
- No confirma que Google indexó una página. Para eso usa la inspección de URL de Search Console.
- No valida la semántica del schema. Detecta JSON-LD roto, no si cumple los requisitos de un resultado enriquecido; para eso está el Rich Results Test de Google.
- Las oportunidades son heurísticas. Un CTR bajo es una pista para investigar, no un error.
- Las impresiones generativas no son citas en ChatGPT o Claude. Puedes importar el CSV del informe generativo de Search Console con
geo-import, pero son impresiones de funciones generativas de Google.
Es de código abierto. Úsalo, rómpelo, cuéntanos.
El código está en GitHub y el paquete en npm, con licencia MIT. Lo hicimos primero para nuestro propio trabajo y lo publicamos para que otros lo usen y lo mejoren. Si te atascas, algo no funciona en tu cliente o sistema operativo, o te falta una comprobación, abre una issue con tu cliente MCP, tu sistema operativo y los pasos para reproducirlo, sin credenciales ni datos privados.
Si lo que necesitas es un sistema propio que conecte tus herramientas y tus datos, eso es lo que hacemos en Grupo Hermoza: software a medida para empresas en Perú.
Preguntas frecuentes.
01
¿Necesito saber programar para usarlo?
No para la primera auditoría: instalas el conector con un comando, pegas la URL de tu web y le pides a tu asistente que ejecute la auditoría. Sí necesitas Node.js 22 o posterior en tu equipo y, para conectar Search Console, crear un cliente OAuth en Google Cloud, un paso que sigue siendo técnico aunque está explicado en el README.
02
¿Puede modificar mi sitio web?
No. De sus 29 herramientas, 28 solo leen y la restante, seo_audit_save, únicamente guarda un informe en tu equipo cuando tú lo pides. Ninguna escribe en tu web, en Search Console ni en Bing. Además, el rastreo respeta el robots.txt y solo visita URL públicas del mismo sitio.
03
¿Funciona con Claude, ChatGPT u otros asistentes?
Funciona con clientes que soporten MCP. El repositorio documenta la configuración para Codex, Claude Desktop y Cursor, y el comando "npx -y seo-webmaster-mcp config codex|claude|cursor" imprime la configuración de cada uno. Otros clientes MCP deberían servir con el mismo comando, pero no los hemos probado todos.
04
¿Reemplaza a un especialista en SEO?
No. Entrega evidencia, URL afectadas y pasos de verificación, y separa los problemas confirmados de las heurísticas. Decidir qué cambiar, en qué orden y si una señal importa para tu negocio sigue requiriendo criterio, y ninguna auditoría automática garantiza posiciones ni indexación.
05
¿Cuánto cuesta?
El paquete es de código abierto con licencia MIT y no cobra por usarlo. Las cuentas de Google Cloud, Search Console y Bing Webmaster Tools las administras tú, con las condiciones de cada servicio.
También puedes leer desarrollo de software con IA en 2026 → o cómo integrar los sistemas de tu empresa →
