Para gente técnica

Monta tu propio Beakman

Tu propio servidor de Beakman, con tu temario, que se actualiza solo cada vez que cambias el repositorio.

Qué vas a montar

Un servidor MCP pequeño, en un contenedor, detrás de HTTPS. No ejecuta ningún modelo de IA: entrega a Claude las instrucciones de Beakman y el temario, y la IA corre en la cuenta de quien estudia. Lee el contenido de tu fork en GitHub y comprueba cada cinco minutos si hay cambios, así que editar el repositorio basta.

Necesitas: una cuenta de GitHub, un servidor con Docker y un dominio con HTTPS. Tiempo: unos 20 minutos.

1. Haz un fork

Haz un fork de icalvete/beakman-mcp. Tiene que ser público, porque el servidor lee el contenido sin credenciales.

• beakman/base.md: la personalidad y el método, comunes a todas las asignaturas.
• <asignatura>/asignatura.md: lo propio de cada asignatura.
• <asignatura>/1eso/ y 2eso/: los temas, un fichero por tema. Un curso con varias asignaturas, como Ciencias de 2º, lleva una subcarpeta por asignatura con un _titulo.txt.
• mcp/: el servidor, en Python.

2. Arranca el servidor

La imagen está publicada y es pública. Dile qué repositorio leer y con qué dominio la vas a servir:

docker run -d --name beakman --restart unless-stopped -p 127.0.0.1:8000:8000 \
  -e BEAKMAN_GITHUB_REPO=TU_USUARIO/beakman-mcp \
  -e BEAKMAN_ALLOWED_HOSTS=beakman.tudominio.com \
  ghcr.io/icalvete/beakman-mcp:latest

Comprueba que ha cargado tu temario:

curl -s -H "Host: beakman.tudominio.com" localhost:8000/up

Debe responder con "ok": true, el commit que ha leído y las cuatro asignaturas.

Para probar en local con una copia del repositorio, sin GitHub: BEAKMAN_REPO_DIR=$PWD uvicorn beakman_mcp.server:app --app-dir mcp.

3. Ponlo detrás de HTTPS

Claude se conecta desde la nube de Anthropic, así que el servidor necesita una dirección pública con HTTPS. Con Caddy basta con esto, y el certificado lo saca él solo:

beakman.tudominio.com {
    reverse_proxy 127.0.0.1:8000
}

Crea en tu DNS un registro A para beakman.tudominio.com con la IP del servidor.

4. Conéctalo a Claude

En claude.ai → Ajustes → Conectores, pulsa Añadir conector personalizado con la URL https://beakman.tudominio.com/mcp. En un chat nuevo, escribe «Quiero estudiar Historia de 2º con Beakman».

Sirve cualquier cliente MCP que admita servidores remotos por HTTP. Hoy, desde España, el que lo permite en cuentas personales es Claude.

5. Edita y listo

• Cómo es Beakman o cómo explica: beakman/base.md.
• Algo de una asignatura: su asignatura.md.
• Un tema nuevo: un fichero en 1eso/ o 2eso/, empezando por su número.

Haces push y, en cinco minutos como mucho, el servidor tiene el contenido nuevo. El código del servidor no lee nada ejecutable del repositorio: solo textos.

6. Opcional: ficheros para Drive

El repositorio trae también un Action, Sincronizar con Drive, que genera tres ficheros por asignatura y los sube a Google Drive con rclone. Sirve para darle el temario a otras herramientas que leen de Drive. Necesita el secreto RCLONE_CONF con un remote de rclone llamado beakman y el permiso drive.file, con tu propia app de Google en producción. Si no lo usas, desactívalo en la pestaña Actions de tu fork, o fallará en cada push.

7. Si algo falla