imap-mcp

Código fuente disponible, no un producto. Este es un servidor IMAP genérico → MCP que se ejecuta en Cloudflare Workers. Se publica bajo MIT para que el código pueda leerse, copiarse y aprenderse de él, pero está construido para, y se ejecuta contra, exactamente un buzón: una cuenta personal de iCloud. No hay compromiso de soporte: los problemas no se clasifican, no se solicitan pull requests, no hay lanzamientos, y nada aquí está versionado para el uso de nadie más. Si te resulta útil, haz un fork.

Es genérico por diseño más que por ambición: el host, el puerto y las credenciales son configuración, no constantes, por lo que debería funcionar con cualquier servidor IMAP. Solo iCloud se ha probado realmente.

Estado: andamiaje. Aún no se ha implementado nada funcional. Ambos workers son marcadores de posición que instalan, lintan, verifican tipos, prueban y pasan una prueba de despliegue en seco. Ver Hoja de ruta.

Qué hace

Indexa un buzón en el almacenamiento de Cloudflare y luego lo sirve a un cliente MCP como herramientas de búsqueda y recuperación, de modo que un modelo pueda responder preguntas sobre quince años de correo sin que el buzón en sí esté en el bucle en cada consulta.

   ┌────────────────────┐  IMAP over TLS   ┌──────────────┐
   │  imap-mcp-sync     │ ───────────────▶ │   mailbox    │
   │  packages/sync     │ ◀─────────────── │   (iCloud)   │
   │  cron, owns creds  │                  └──────────────┘
   └─────────┬──────────┘
             │ writes                    ▲ writes proxied over
             ▼                           │ a service binding
   ┌────────────────────┐                │
   │  D1 (+FTS5) and R2 │                │
   └─────────┬──────────┘                │
             │ reads                     │
             ▼                           │
   ┌────────────────────┐────────────────┘   ┌──────────────┐
   │  imap-mcp-server   │  Streamable HTTP   │  MCP client  │
   │  packages/mcp      │ ◀───────────────── │  behind CF   │
   │  stateless, no creds                    │  Access      │
   └────────────────────┘                    └──────────────┘

Dos workers, y la división entre ellos es el diseño de seguridad más que una elección de empaquetado:

• packages/sync (imap-mcp-sync) es la única parte del sistema que habla IMAP. Contiene la contraseña específica de la aplicación, que en iCloud otorga acceso completo al buzón incluido el envío SMTP, por lo que esa credencial existe en exactamente un lugar.

• packages/mcp (imap-mcp-server) es un lector sin estado. Consulta el índice, nunca el buzón, y envía las pocas operaciones de escritura de vuelta al worker de sincronización a través de un enlace de servicio en lugar de abrir una conexión propia.

Related MCP server: gmail-mcp

Inicio rápido

pnpm install         # installs both packages
pnpm run lint        # biome check (lint + format)
pnpm run typecheck   # wrangler types + tsc --noEmit
pnpm run test        # vitest, inside workerd
pnpm run dead-code   # knip
pnpm run build       # wrangler deploy --dry-run, both workers

Por paquete, desde packages/sync o packages/mcp: pnpm run dev, pnpm run test:watch, pnpm run deploy.

Configuración

Este repositorio es público, por lo que no se confirman valores específicos de despliegue: ni ID de cuenta de Cloudflare, ni etiqueta de zona, ni dominio de equipo de Cloudflare Access ni audiencia de aplicación (AUD), ni dirección de buzón. Ninguno de los wrangler.jsonc contiene un account_id, y el worker MCP no declara ninguna ruta en absoluto.

Todo lo que necesitarías proporcionar está nombrado y explicado en .env.example. Cópialo a .env y complétalo. En resumen:

Localmente, los secretos van en un .dev.vars ignorado por git por paquete; cada uno tiene un .dev.vars.example para copiar.

Ambos workers son inaccesibles por defecto

workers_dev y preview_urls son false en ambos archivos wrangler.jsonc, y el worker MCP no declara ninguna ruta. Por lo tanto, un despliegue nuevo no es accesible desde Internet. Esto es deliberado: sin una valla de carpetas, el endpoint MCP es funcionalmente acceso de lectura a un buzón completo, por lo que no debe volverse accesible antes de que Cloudflare Access esté delante de él. Sin workers_dev: false, un worker está activo en <name>.<account>.workers.dev sin importar qué rutas o políticas de Access existan.

Una guía completa de despliegue desde cero (secretos, configuración de Access, bindings, migraciones y el relleno inicial) aún no está escrita; llegará con el resto del sistema.

Hoja de ruta

Seguimiento como issues en este repositorio:

Un spike resolvió la única pregunta de la que dependía toda la arquitectura: ¿puede un Cloudflare Worker hablar IMAP con iCloud? Puede: TLS y LOGIN en el puerto 993 en 755 ms, carpetas listadas, mensajes obtenidos y decodificados en MIME, un borrador añadido y marcado. Así que la ruta de sincronización es un Worker y nada se mueve a un Contenedor. Los hallazgos que limitan el diseño — orden de CONDSTORE, sin MOVE en iCloud, SEARCH inutilizable para contenido — están escritos en los tickets que afectan.

Licencia

MIT — ver LICENSE.