Claude-Atlas-MCP

Servidor MCP autoalojado que le da a Claude memoria persistente entre conversaciones — entidades, observaciones, historial, recordatorios programados, además de una bandeja para cosas que llegan y un estante para ideas — en un backend ligero de Node/SQLite que tú mismo ejecutas.

Conéctalo a Claude como conector MCP y podrá recordar en qué estás trabajando de una conversación a la siguiente: proyectos en curso, decisiones y su razonamiento, datos sobre ti y tu configuración, y cosas que deben reaparecer en una fecha futura.

Por qué

Claude lo olvida todo cuando termina una conversación. Atlas es una capa de memoria pequeña, sencilla y duradera que controlas de principio a fin — sin servicios de terceros, sin dependencia de un proveedor. Es un único proceso de Node respaldado por un solo archivo SQLite. Ejecútalo en un servidor doméstico, un VPS o tu portátil.

Empieza en blanco a propósito. No hay un esquema de tu vida predefinido, ni un trabajo asumido, ni un rastreador de incidencias obligatorio — solo una forma que se va llenando a medida que la usas.

Related MCP server: Cortex

Inicio rápido

git clone https://github.com/dcazman/Claude-Atlas-MCP.git
cd Claude-Atlas-MCP
docker compose up -d --build
docker compose logs atlas-mcp

Sin .env, sin token, sin configuración. En el primer inicio, Atlas crea la base de datos, genera un token por ámbito y los imprime:

    work     3f2a…   (caller "work-client")
    personal 9c41…   (caller "personal-client")
    shared   b7e0…   (caller "shared-client")

  Connect a client to:  http://localhost:7784/atlas-mcp?token=<one of the above>

Los tokens se guardan junto a la base de datos y se reutilizan en cada reinicio. Los datos viven en ./data, un único archivo SQLite. Esa es toda la configuración.

Comprueba que funciona:

curl -s localhost:7784/health
# {"ok":true,"service":"atlas-mcp","version":2,"port":"7784"}

TOKEN=<one of the tokens printed above>
curl -s -X POST localhost:7784/atlas-mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-atlas-token: $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":
       {"name":"add_observation","arguments":
        {"section":"work","entity":"Atlas","content":"Installed today."}}}'

Si eso devuelve un observation_id, toda la pila funciona: tu primer recuerdo está en disco y Claude puede leerlo.

CI publica una imagen en cada push a main, si prefieres no compilar:

docker run -d --name atlas -p 7784:7784 -v "$PWD/atlas-data:/app/data" \
  ghcr.io/dcazman/claude-atlas-mcp:latest
docker logs atlas

Node puro — 22.13+ para el node:sqlite integrado. Sin dependencias nativas, nada que compilar:

npm install
npm start

Para elegir tus propios tokens, zona horaria u hora de limpieza en lugar de los valores predeterminados, cp .env.example .env y descomenta lo que quieras. Copiarlo sin editar no cambia nada — cada línea está comentada a propósito.

Modelo de datos

El embudo

Tres superficies, en orden creciente de compromiso:

  shelf  ──graduate──▶  tray  ──promote──▶  memory
 (ideas)              (triage)          (observations)

• El estante guarda cosas que se te ocurrieron. Una idea que lleva un año ahí no es un fallo del backlog — es el estante funcionando. Las ideas salen graduándose a la bandeja o eliminándose a propósito, conservando el motivo.

• La bandeja guarda cosas que llegaron. Es una cola, no un montón: captura, luego promueve, fusiona o descarta.

• La memoria es la parte que Claude lee al inicio de una conversación.

Nada se destruye en el camino. Los elementos resueltos dejan de aparecer pero conservan su historial, incluido en qué se convirtieron.

Cómo ves realmente esto. get_landscape es la única llamada que Claude hace al inicio de una conversación, así que todo lo que necesite tu atención tiene que volver en ella:

Así que "captura ahora, decide después" funciona: lo que dejes en la bandeja a mitad de conversación vuelve al inicio de la siguiente, sin que tengas que recordar que existe.

Herramientas

31 herramientas MCP.

Lectura

• get_landscape — todo en una sección (con shared fusionado): todas las entidades con sus observaciones, recordatorios vencidos, elementos de bandeja sin clasificar y un recuento de ideas abiertas en el estante. Llámala al inicio de una conversación para orientarte.

• search — búsqueda por palabras clave en entidades, observaciones e historial.

• get_entity — una entidad y sus observaciones por nombre.

• get_observation — recupera hasta 20 observaciones directamente por id. Los ids son estables y nunca se reutilizan, lo que los convierte en una forma económica de pasar datos concretos de una conversación a la siguiente.

• get_history — la línea de tiempo de los eventos registrados.

• get_time — hora actual más el tiempo transcurrido desde la última llamada de este token.

Escritura

• upsert_entity — crea o actualiza el nombre/resumen de una entidad.

• add_observation — asocia un dato a una entidad.

• update_observation — edita un dato en el sitio; el id permanece estable. Funciona en filas protegidas.

• remove_observation — elimina un dato obsoleto o completado (se niega si está protegido).

• protect_observation / unprotect_observation — marca un dato como no eliminable, o retira esa marca.

• remove_entity — elimina una entidad y sus observaciones (se niega si alguna está protegida).

• log_event — registra un evento notable en el historial.

Recordatorios

• create_reminder — una nota con una trigger_date, una trigger_time opcional y un enlace opcional a una entidad.

• list_reminders — todo lo programado, vencido o no.

• list_due_reminders — todo lo que vence ahora mismo. Esto es lo que consulta un notificador.

• mark_reminder_fired — sella un recordatorio programado como entregado para que nunca se dispare dos veces.

• dismiss_reminder — marca un recordatorio como gestionado (deja de aparecer).

• remove_reminder — elimina un recordatorio por completo.

Bandeja

• pending_add — captura algo que llegó.

• pending_list — lo que aún necesita clasificación, de más antiguo a más reciente.

• pending_promote — convierte una captura en una observación de una entidad.

• pending_merge — fusiona un duplicado en el que vas a conservar.

• pending_dismiss — decide que no necesita nada, conservando el motivo.

• pending_reopen — deshace cualquiera de las anteriores.

Estante

• research_add — aparca una idea.

• research_list — ideas abiertas, de más antiguas a más recientes.

• research_promote — gradúa una idea a la bandeja.

• research_kill — retira una idea a propósito, con el motivo.

• research_reopen — la vuelve a poner.

Cada respuesta de herramienta incluye un pequeño pie de tiempo — hora actual del servidor en tu zona horaria configurada, más el tiempo transcurrido desde la última llamada de ese token — para que el modelo nunca tenga que adivinar ni hacer cálculos de fechas con un reloj mental desactualizado.

Recibir notificaciones

Atlas nunca envía nada por sí solo — no tiene idea de dónde querrías que te llegaran las notificaciones. En su lugar, list_due_reminders es el contrato para cualquier cosa que las envíe:

1. Consulta list_due_reminders con el intervalo que prefieras.

2. Entrega las filas que llevan una trigger_time (las pasivas solo esperan verse en el paisaje).

3. Llama a mark_reminder_fired en cada una de las que entregaste.

El paso 3 es lo que hace que la entrega sea exactamente una vez: el sello está protegido en SQL, así que dos consultores superpuestos no pueden enviar dos veces. Una docena de líneas de un script con cron es suficiente para conectarlo a correo electrónico, un webhook de chat o una notificación de teléfono.

Trabajador de limpieza

src/groom.js se ejecuta cada noche dentro del proceso del servidor (sin necesidad de cron en el host), o bajo demanda con npm run groom. Es intencionadamente solo de informe y mecánico — sin llamadas a LLM, sin eliminación de tus datos:

• señala probables observaciones casi duplicadas dentro de una entidad

• señala entidades inactivas (60+ días sin tocar) como candidatas a archivo/compresión

• señala recordatorios descartados hace tiempo (90+ días) como candidatos a eliminación

• rota su propio audit_log (90+ días) — lo único que realmente elimina

• omite entidades sin tocar desde la última ejecución, así que las ejecuciones repetidas son baratas

Los hallazgos van a una entidad "Informe de limpieza" por sección para que tú (o Claude) actúes sobre ellos. Se ejecuta a ATLAS_GROOM_HOUR (por defecto 4am) en tu zona horaria, y se autocorrige: una ventana perdida porque el contenedor estaba caído se ejecuta en la siguiente comprobación.

Conectar Claude

Atlas habla MCP sobre HTTP transmisible en POST /atlas-mcp. Añádelo como conector usando la URL del servidor con tu token:

https://<your-host>/atlas-mcp?token=<your-secret>

El token es la mitad secreta de un triple ATLAS_TOKEN (consulta Configuración). También puedes pasarlo como cabecera X-Atlas-Token o como token Bearer en lugar de en la cadena de consulta.

No hay section en la URL — cada herramienta recibe un argumento section, y cuál debe usar por defecto una conversación determinada se configura mejor en las instrucciones personalizadas de tu proyecto de Claude (p. ej. "Tu sección de Atlas es personal"). Hay un endpoint GET /health disponible para comprobaciones de actividad.

Para uso real querrás tenerlo detrás de HTTPS — un proxy inverso o un túnel (Cloudflare Tunnel, Tailscale, nginx, etc.) delante del contenedor. El token es la única autenticación, así que no expongas el puerto públicamente sin TLS.

Una vez conectado, un buen hábito es que Claude llame a get_landscape al inicio de cada conversación y mantenga las entradas actualizadas a medida que cambian las cosas. El servidor incluye instrucciones que dicen exactamente eso, así que la mayoría de los clientes lo adoptan sin que escribas nada.

Protegerlo

La autenticación integrada de Atlas es un token compartido — suficiente detrás de una red privada o un túnel, pero escasa si lo expones a internet. Para control de acceso real, pon una pasarela de autenticación dedicada delante en lugar de endurecer este servidor tú mismo.

mcp-auth-proxy es un gateway OAuth 2.1 / OIDC de integración directa para servidores MCP — sin cambios de código en Atlas:

• Autentícate contra tu propio IdP (Google, GitHub, Okta, Auth0, Azure AD, Keycloak, cualquier proveedor OIDC), con una contraseña opcional.

• Autoriza usuarios por coincidencia exacta o glob (p. ej. *@yourcompany.com).

• Termina TLS y proxy de transportes HTTP tal cual, verificado en Claude, Claude Code, ChatGPT, Copilot y Cursor.

En términos generales, lo apuntarías al endpoint HTTP de Atlas:

./mcp-auth-proxy \
  --external-url https://<your-domain> \
  --tls-accept-tos \
  -- http://localhost:7784/atlas-mcp

Consulta su documentación para la configuración del IdP. (No afiliado — solo un ajuste limpio para servidores MCP autoalojados como este).

Configuración

Todo opcional. Se configura mediante .env (consulta .env.example) o el entorno:

Haciéndolo tuyo

El diseño es deliberadamente pequeño para que puedas extenderlo sin luchar contra él.

• Añadir una herramienta. Todo vive en src/tools.js, registrado a través de un envoltorio guarded() que realiza la comprobación de ámbito y la escritura de auditoría. Una nueva herramienta es un bloque guarded(name, {description, inputSchema}, handler) más una función en src/db.js. La descripción importa más que el código — es lo que Claude lee para decidir cuándo usarla.

• Añadir una tabla. Las migraciones son una escalera PRAGMA user_version en src/db.js: incrementa el número, escribe SQL aditivo protegido por él, listo. Cada migración es idempotente y se ejecuta al arrancar, por lo que actualizar es solo reiniciar.

• Empujar reglas a la base de datos. El estilo de la casa aquí es que una regla que tienes que recordar es una regla que se rompe — así que resolved_at es sellado por un disparador, el ámbito se aplica del lado del servidor, y las filas protegidas están protegidas en SQL. Sigue el patrón y tus adiciones lo heredarán.

• Cambiar las secciones. work/personal/shared están fijados en las restricciones CHECK del esquema y el mapa de ámbito en src/server.js. Renombrarlos es una migración más una edición de dos líneas en el mapa — vale la pena si el vocabulario no se ajusta a tu vida.

Pruebas

npm test

Cada ejecución comienza desde una base de datos vacía, por lo que el conjunto de pruebas sirve también como verificación de pizarra en blanco: el esquema se construye desde cero, la matriz de ámbito de tokens se mantiene (incluyendo que los ids fuera de ámbito son indistinguibles de los inexistentes), los recordatorios temporizados se disparan exactamente una vez, y el embudo mueve los elementos como afirma hacerlo.

Seguridad

Consulta SECURITY.md para el modelo de amenazas, notas de endurecimiento de despliegue y cómo reportar una vulnerabilidad.

Cambios

Consulta CHANGELOG.md. La versión corta: v3 añadió la bandeja, el estante, recordatorios temporizados, direccionamiento por id de observación y un inicio sin configuración.

Licencia

MIT — consulta LICENSE.