Respuesta rápida: Para instalar OpenSEO en Cloudflare Workers necesitas una cuenta de GitHub, una de Cloudflare y una de DataForSEO. Subes el código a un repositorio privado, creas en Cloudflare una base D1, dos espacios KV y un bucket R2, conectas el repositorio a Workers Builds y configuras como secretos el inicio de sesión, tu clave Base64 de DataForSEO y el cliente OAuth de Google para Search Console y Analytics.
Introducción
Pagar 100 o 200 dólares al mes por una suite SEO tiene sentido si la usas a diario. Si solo necesitas investigar keywords, auditar tu sitio y cruzar los datos con Search Console, el gasto se vuelve difícil de justificar. Por eso en KodFlux probamos OpenSEO, una herramienta SEO open source que puedes alojar tú mismo, y la desplegamos de principio a fin en Cloudflare.
En esta guía te mostramos cómo instalar OpenSEO en Cloudflare Workers paso a paso: desde crear tu cuenta de GitHub y abrir el proyecto en Claude Code, hasta conectar DataForSEO, Google Search Console y Google Analytics. También documentamos los errores reales que nos salieron en el camino y cómo los resolvimos, para que no pierdas horas con ellos.
Qué es OpenSEO y por qué alojarlo en Cloudflare
OpenSEO es una plataforma SEO de código abierto. Obtiene los datos de mercado (keywords, SERP, backlinks y dominios) de DataForSEO, un servicio que cobras solo por lo que consultas, y los datos de tu propio sitio de Google Search Console y Google Analytics 4.
Estas son las herramientas que incluye:
- Investigación: Keyword Research, Domain Overview y Backlinks.
- Visibilidad en IA: Prompt Research, Prompt Explorer y Prompt Tracking, para ver cómo te mencionan los asistentes de IA.
- Tu sitio: GSC Insights, Rank Tracking, Local SEO, Saved Keywords y Site Audit.
- Agentes: servidor MCP para usar OpenSEO desde Claude, ChatGPT, Cursor u otros agentes.
Cloudflare Workers encaja bien con este tipo de proyecto por tres razones:
- No administras servidores: la app corre en la red de Cloudflare y escala sola.
- Todo queda en una cuenta: base de datos (D1), caché (KV), archivos (R2) y tareas en segundo plano (Workflows).
- Costo bajo: para un uso personal o de una agencia pequeña, el gasto principal son las consultas a DataForSEO.
Si te interesa usar OpenSEO desde un agente de IA, complementa esta guía con nuestro artículo sobre skills de SEO con IA para agentes.
Arquitectura de OpenSEO en Cloudflare Workers
Antes de empezar conviene entender qué vas a crear, porque la mayoría de errores de despliegue vienen de no saberlo. OpenSEO no es un solo Worker: son dos, y comparten la misma base de datos.
| Recurso | Para qué sirve |
|---|---|
| Worker principal | La app web, la API, el servidor MCP y las tareas programadas. |
| Worker open-seo-audit | El motor de auditorías de sitio. No tiene dirección pública: el principal lo llama por dentro. |
| D1 (base de datos) | Usuarios, proyectos, keywords, auditorías y conexiones de Google. |
| KV (2 espacios) | Uno de caché general y otro para los tokens OAuth del servidor MCP. |
| R2 (bucket) | Caché de las respuestas de DataForSEO y archivos de las auditorías. |
| Workflows y Durable Objects | Procesos largos: auditorías, revisión de rankings, visibilidad en IA y el chat del agente. |
Requisitos y costos antes de empezar
Necesitas lo siguiente:
- Una cuenta de GitHub para guardar tu copia del código.
- Una cuenta de Cloudflare. Si vas a lanzar muchas auditorías, revisa los límites de tu plan de Workers; con uso intensivo conviene el plan de pago.
- Una cuenta de DataForSEO. Las cuentas nuevas traen 1 dólar de crédito para probar y la recarga mínima es de 50 dólares.
- Una cuenta de Google con tu sitio verificado en Search Console y, si quieres, una propiedad de GA4.
- Un dominio en Cloudflare si quieres usar una dirección propia, como
seo.tu-dominio.com. Es opcional. - En tu computadora: Git, Node.js 22 o superior y pnpm 10.
Paso 1: Crear tu cuenta de GitHub
- Entra a github.com y haz clic en Sign up.
- Elige un nombre de usuario, un correo y una contraseña, y confirma el correo.
- Activa la autenticación en dos pasos en Settings → Password and authentication. Vas a guardar ahí claves de tu infraestructura, así que vale la pena.
Consejo de privacidad: en Settings → Emails activa Keep my email addresses private. GitHub te da una dirección anónima del tipo usuario@users.noreply.github.com para firmar tus commits sin exponer tu correo.
Paso 2: Instalar Git, Node.js, pnpm y Claude Code
En macOS o Linux, abre la Terminal y comprueba qué tienes instalado:
git --version
node --version
Si te falta Node.js, instálalo desde nodejs.org (versión LTS). Después activa pnpm, que viene incluido con Node:
corepack enable
Para instalar Claude Code, el agente de programación de Anthropic que usamos para revisar el código y resolver errores durante el despliegue:
npm install -g @anthropic-ai/claude-code
Consulta la documentación oficial de Claude Code si prefieres otro método de instalación.
Paso 3: Clonar OpenSEO y subirlo a tu GitHub
Vamos a crear una copia del código en un repositorio privado tuyo. Así puedes hacer cambios y conectarlo a Cloudflare.
- En GitHub, haz clic en New repository. Ponle un nombre (por ejemplo
mi-openseo), márcalo como Private y no agregues README ni licencia: tiene que quedar vacío. - En la Terminal, clona OpenSEO y entra a la carpeta:
git clone https://github.com/every-app/open-seo.git
cd open-seo
- Conecta tu repositorio y sube el código. Cambia
TU_USUARIOymi-openseopor los tuyos:
git remote add mio https://github.com/TU_USUARIO/mi-openseo.git
git push -u mio main
- Para que tus commits no lleven tu correo personal, configura la dirección anónima solo en este proyecto:
git config user.email "TU_USUARIO@users.noreply.github.com"
El remoto origin sigue apuntando al proyecto original. Te servirá más adelante para traer actualizaciones.
Paso 4: Crear el proyecto en Claude Code
Desde la carpeta del proyecto, inicia Claude Code:
claude
La primera vez te pide iniciar sesión con tu cuenta de Claude. A partir de ahí puedes pedirle en lenguaje natural lo que necesitas. Estos son algunos de los pedidos que nos ahorraron más tiempo:
- “Revisa wrangler.jsonc y dime qué recursos de Cloudflare tengo que crear.”
- “Revisa este log de Workers Builds y dime por qué falla el despliegue.”
- “¿Qué variables necesita OpenSEO para el modo de inicio de sesión con contraseña?”
Claude Code lee el código y la documentación del repositorio antes de responder, así que sus respuestas se basan en tu versión exacta de OpenSEO.
Paso 5: Crear la base de datos y el almacenamiento en Cloudflare
El archivo wrangler.jsonc del repositorio trae los identificadores de los recursos del proyecto original, que no existen en tu cuenta. Si despliegas sin cambiarlos, Cloudflare responde con un error como KV namespace not found. Hay que crear los tuyos.
- Inicia sesión en Cloudflare desde la Terminal:
pnpm install
pnpm exec wrangler login
- Crea los cuatro recursos. Puedes cambiar
mi-openseopor el nombre que prefieras:
pnpm exec wrangler kv namespace create mi-openseo-kv
pnpm exec wrangler kv namespace create mi-openseo-oauth-kv
pnpm exec wrangler d1 create mi-openseo
pnpm exec wrangler r2 bucket create mi-openseo
Cada comando muestra el id del recurso creado. Cópialos.
- Reemplaza los valores en los dos archivos de configuración:
- En
wrangler.jsonc: eliddeKVy deOAUTH_KV, eldatabase_namey eldatabase_idde D1, y elbucket_namede R2. - En
wrangler.audit.jsonc: los mismos valores deKV, D1 y R2. Este archivo no llevaOAUTH_KV.
-
Si quieres, cambia también el
namedel Worker principal enwrangler.jsonc(por ejemplo,mi-openseo). No cambies el nombreopen-seo-audit: el Worker principal lo busca por ese nombre. -
Guarda los cambios y súbelos:
git add wrangler.jsonc wrangler.audit.jsonc
git commit -m "Usar mis recursos de Cloudflare"
git push mio main
Paso 6: Desplegar los dos Workers con Workers Builds
Workers Builds compila y despliega tu app automáticamente cada vez que haces git push.
6.1 Desplegar primero el Worker de auditorías
El Worker principal depende de open-seo-audit, así que este va primero. Despliégalo una vez desde tu computadora:
pnpm run build
pnpm exec wrangler deploy -c dist/open_seo_audit/wrangler.json
6.2 Conectar el Worker principal a GitHub
- En el panel de Cloudflare, ve a Workers y Pages → Crear → Importar un repositorio y elige tu repositorio privado.
- En Configuración de compilación, usa exactamente estos valores:
| Campo | Valor |
|---|---|
| Comando de compilación | pnpm run build |
| Comando de implementación | npx wrangler d1 migrations apply DB —remote && npx wrangler deploy |
| Directorio raíz | / |
- Guarda y lanza la primera compilación. El comando de implementación crea las tablas en tu base de datos y después despliega la app.
Importante: no agregues el despliegue de open-seo-audit a este comando. Workers Builds le pone el nombre del Worker conectado a todo lo que despliega, así que intentaría reemplazar tu app con el código de auditorías y fallaría con un error sobre SamChatAgent. Si más adelante quieres que las auditorías también se actualicen solas, conecta el repositorio por separado al Worker open-seo-audit, con el comando de implementación npx wrangler deploy -c dist/open_seo_audit/wrangler.json.
Puede que Cloudflare abra un pull request en tu repositorio para “corregir” el nombre del Worker. Ciérralo sin fusionarlo.
Paso 7: Conectar un dominio propio
- Abre tu Worker principal en Workers y Pages.
- Ve a Configuración → Dominios y rutas → Agregar → Dominio personalizado.
- Escribe el subdominio, por ejemplo
seo.tu-dominio.com. El dominio tiene que estar en tu cuenta de Cloudflare.
Configura el dominio antes de crear cuentas: el inicio de sesión queda ligado a esa dirección y cambiarla después cierra todas las sesiones.
Paso 8: Configurar el inicio de sesión con email y contraseña
Si abres la app ahora, verás el aviso “Authentication setup required”. OpenSEO tiene dos formas de proteger el acceso:
- Email y contraseña (
AUTH_MODE=password): la primera persona que se registra queda como administrador y el resto entra por invitación. Es la opción más simple. - Cloudflare Access: Cloudflare verifica a cada visitante antes de que llegue a la app. Es más seguro, pero requiere configurar Zero Trust.
Para el modo con contraseña, genera dos claves aleatorias con este comando (ejecútalo dos veces):
openssl rand -hex 32
Después crea estos secretos en tu Worker principal. Cada comando te pide el valor sin mostrarlo en pantalla. Cambia mi-openseo por el nombre de tu Worker:
pnpm exec wrangler secret put AUTH_MODE --name mi-openseo
pnpm exec wrangler secret put BETTER_AUTH_URL --name mi-openseo
pnpm exec wrangler secret put BETTER_AUTH_SECRET --name mi-openseo
pnpm exec wrangler secret put OPENSEO_OPERATOR_SECRET --name mi-openseo
| Secreto | Valor |
|---|---|
AUTH_MODE | password |
BETTER_AUTH_URL | La dirección de tu app, por ejemplo https://seo.tu-dominio.com, sin barra al final. |
BETTER_AUTH_SECRET | La primera clave aleatoria. También cifra los tokens de Google, así que no la cambies después. |
OPENSEO_OPERATOR_SECRET | La segunda clave. Permite restablecer contraseñas desde la Terminal. Guárdala en un lugar seguro. |
Haz esto en cuanto termines: abre tu app y crea tu cuenta. La primera persona que se registra queda como administrador y, a partir de ahí, el registro se cierra.
Paso 9: Crear tu cuenta de DataForSEO y conectar la API
- Regístrate en DataForSEO y confirma tu correo.
- Entra a API Access en tu panel. Verás tres datos: API login, API password y Base64 format.
- Copia el valor de Base64 format. OpenSEO necesita ese valor completo, no el login ni la contraseña por separado.
Si no te deja copiarlo, puedes generarlo con tu API login y tu API password. No uses el correo ni la contraseña con los que entras al panel:
printf 'TU_API_LOGIN:TU_API_PASSWORD' | base64
Guarda el valor como secreto en los dos Workers:
pnpm exec wrangler secret put DATAFORSEO_API_KEY --name mi-openseo
pnpm exec wrangler secret put DATAFORSEO_API_KEY --name open-seo-audit
Cuidado: no hagas clic en Reset password en DataForSEO. Si cambias la contraseña de la API, el valor Base64 que guardaste deja de funcionar.
Paso 10: Conectar Google Search Console y Google Analytics
Con un solo cliente OAuth de Google conectas las dos integraciones.
10.1 Crear el proyecto y activar las APIs
- Entra a Google Cloud Console y crea un proyecto.
- Con ese proyecto seleccionado, habilita estas tres APIs:
10.2 Configurar la pantalla de consentimiento
En APIs y servicios → Pantalla de consentimiento de OAuth:
- Elige el tipo de usuario Externo.
- Completa el nombre de la app, el correo de asistencia y el de contacto.
- En Usuarios de prueba, agrega la cuenta de Google que tiene acceso a tu Search Console y a tu Analytics.
- Haz clic en Publicar app. Si la dejas en modo de prueba, Google desconecta la integración cada 7 días. Al conectar verás un aviso de “app no verificada”: es normal para uso personal, sigue con Configuración avanzada.
10.3 Crear el ID de cliente
En APIs y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth:
- Tipo de aplicación: Aplicación web.
- En URIs de redireccionamiento autorizados, agrega estas dos, con tu dominio y sin barra al final:
https://seo.tu-dominio.com/api/gsc/oauth/callback
https://seo.tu-dominio.com/api/ga4/oauth/callback
- Guarda y copia el ID de cliente y el Secreto del cliente.
10.4 Guardar las credenciales y conectar
Crea los dos secretos solo en el Worker principal:
pnpm exec wrangler secret put GOOGLE_CLIENT_ID --name mi-openseo
pnpm exec wrangler secret put GOOGLE_CLIENT_SECRET --name mi-openseo
Después, en OpenSEO:
- Search Console: en el panel de tu proyecto, haz clic en Connect with Google y elige tu propiedad.
- Analytics: ve a Project settings → Integrations → Google Analytics → Connect y elige tu propiedad GA4. Google pide un permiso aparte.
Paso 11: ¿Necesitas Cloudflare Zero Trust?
Con el modo de email y contraseña, tus datos ya están protegidos. Lo comprobamos en el código y en producción:
- Cada consulta de datos exige sesión. Sin sesión, el servidor responde
UNAUTHENTICATEDy no devuelve nada. - Los proyectos se filtran por organización. Aunque alguien tenga cuenta y conozca el enlace de tu proyecto, no puede abrirlo si no es miembro.
- El registro está cerrado desde que se crea el administrador.
- Los intentos de inicio de sesión tienen límite, lo que frena los ataques de fuerza bruta.
Zero Trust agrega una capa extra: bloquea a bots y atacantes antes de que lleguen a la app. Si lo activas, ten en cuenta que los clientes MCP no podrán conectarse sin configurar excepciones, y que tus compañeros necesitarán estar en la política de acceso y además en la organización de OpenSEO.
Cómo verificar que todo funciona
OpenSEO incluye una página de diagnóstico. Ábrela en el navegador:
https://seo.tu-dominio.com/api/health
| Comprobación | Qué debe decir |
|---|---|
status | ok |
auth | ok, en modo password |
dataforseo | ok |
gsc | ok, configurado |
database | ok |
Las líneas de ai (el agente SAM, que necesita una clave de OpenRouter) y rendering son opcionales.
Errores comunes al desplegar OpenSEO y cómo resolverlos
Estos son los errores que nos aparecieron durante el despliegue, con su solución:
| Error | Causa y solución |
|---|---|
KV namespace not found (código 10041) | Los archivos de configuración tienen los identificadores del proyecto original. Crea tus recursos y reemplázalos (paso 5). |
Syntax error: end of file unexpected | El comando de compilación termina en &&. Déjalo solo como pnpm run build. |
does not export class ‘SamChatAgent’ (código 10064) | El comando de implementación incluye el despliegue de open-seo-audit. Quítalo y despliega ese Worker por separado (paso 6). |
Authentication setup required | Falta AUTH_MODE. Configura los secretos del paso 8. |
does not decode as base64 of login:password | El valor de DataForSEO está mal copiado: con un prefijo Basic, comillas o cortado. Vuelve a generarlo (paso 9). |
redirect_uri_mismatch | Las URIs del cliente OAuth no coinciden. Revisa que usen https y no terminen en /. Google puede tardar unos minutos en aplicar los cambios. |
access_denied en Google | Tu cuenta no está en Usuarios de prueba, o falta publicar la app. |
Too many requests | Muchas consultas a la vez. Espera un minuto y usa Try again. |
¿Prefieres auditar tu sitio sin instalar nada?
Prueba nuestras herramientas gratuitas para desarrolladores y revisa el SEO técnico de tu web en segundos.
Ver herramientas de KodFluxMantenimiento: actualizaciones y contraseñas
Traer las novedades de OpenSEO
El proyecto original recibe mejoras con frecuencia. Para incorporarlas a tu copia:
git fetch origin
git merge origin/main
git push mio main
Si Git marca un conflicto en wrangler.jsonc o wrangler.audit.jsonc, conserva tus identificadores de recursos. Cada git push dispara un nuevo despliegue automático.
Restablecer una contraseña olvidada
OpenSEO autoalojado no envía correos, así que no hay opción de “olvidé mi contraseña”. El administrador la restablece desde la Terminal con la clave OPENSEO_OPERATOR_SECRET (guárdala en un archivo .env.selfhost, que Git ignora):
bash -c 'read -rs -p "Nueva contraseña: " P; echo; printf "%s\n" "$P" | OPENSEO_URL=https://seo.tu-dominio.com pnpm selfhost:admin reset-password usuario@correo.com'
Preguntas frecuentes sobre OpenSEO en Cloudflare
¿OpenSEO es gratis?
Sí. OpenSEO es de código abierto y no cobra por usarlo. Pagas la infraestructura de Cloudflare, que para uso personal suele ser mínima, y las consultas a DataForSEO. Los datos de Search Console y Analytics vienen de tu propia cuenta de Google, así que no generan costo adicional.
¿Cuánto cuesta DataForSEO para usar OpenSEO?
DataForSEO funciona con pago por uso: no hay mensualidad fija. Las cuentas nuevas reciben 1 dólar de crédito de prueba y la recarga mínima es de 50 dólares. El crédito se descuenta solo cuando consultas keywords, SERP, backlinks o dominios.
¿Es seguro alojar OpenSEO sin Cloudflare Zero Trust?
Sí, con el modo de email y contraseña. Cada consulta exige sesión iniciada, los proyectos se filtran por organización y el registro se cierra tras crear el administrador. Zero Trust es una capa adicional recomendable si manejas datos de clientes, pero no es obligatoria.
¿Puedo usar OpenSEO desde Claude o ChatGPT?
Sí. OpenSEO incluye un servidor MCP en la ruta /mcp de tu instalación. Con el modo de email y contraseña, los clientes MCP inician sesión con tu misma cuenta de OpenSEO, sin configuración adicional en Cloudflare.
Conclusión
Instalar OpenSEO en Cloudflare Workers te da una suite SEO completa y privada, con keyword research, auditorías, rank tracking y datos reales de Search Console y Analytics, por el costo de lo que consultes en DataForSEO. El proceso tiene varias piezas, pero con esta guía y los errores ya documentados puedes tenerlo funcionando en una tarde.
Si quieres llevarlo un paso más allá, conecta OpenSEO a tu agente de IA y revisa nuestra guía de skills de SEO con IA para agentes.