mail-mcp

Servicio de correo autoalojado e independiente del proveedor. Apúntalo a las credenciales IMAP/SMTP de cualquier buzón y expone:

• API REST que refleja las operaciones comunes de buzón: listar carpetas, listar/obtener/buscar mensajes, enviar, marcar, mover, eliminar, cuota (mejor esfuerzo).

• Webhooks (message.received) mediante un vigilante IMAP IDLE persistente: lanza un HTTP POST (con un secreto bearer por webhook) cada vez que llega un nuevo correo, reintentado con retroceso exponencial (hasta 6 intentos) si el endpoint receptor falla.

• Servidor MCP (HTTP Streamable, POST /mcp) que expone las mismas operaciones como herramientas, para que cualquier agente compatible con MCP pueda usarlo directamente.

Multibuzón desde el inicio: añade tantas cuentas como quieras en config/accounts.json.

Los cuerpos de las solicitudes en la API REST se validan con Zod (lib/schemas.js) — las cargas útiles inválidas reciben un 422 ERR_VALIDATION_FAILED con errores a nivel de campo en lugar de llegar a la capa de correo. Las suscripciones a webhooks persisten en SQLite (config/webhooks.sqlite, mediante better-sqlite3) en lugar de un archivo JSON plano. Los mensajes mayores que MAIL_MCP_MAX_MESSAGE_SIZE (por defecto 25MB) se devuelven con bodyTruncated: true y sin cuerpo/adjuntos analizados, para evitar cargar mensajes enormes en memoria.

Configuración

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

Copia config/accounts.json.example a config/accounts.json (gitignored — tampoco hay contraseñas en este archivo, esas solo viven en .env):

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

La contraseña para la cuenta id: "example" se lee de MAILMCP_PASS_EXAMPLE.

node index.js

Se ejecuta en 127.0.0.1:4900 por defecto (ver MAIL_MCP_PORT). Ponlo detrás de un proxy inverso con TLS si necesitas acceder desde fuera del host.

Related MCP server: Agent Email

systemd

Una unidad de ejemplo está en deploy/mail-mcp.service — cópiala a /etc/systemd/system/, ajusta las rutas, y carga los secretos desde /root/mail-mcp/.env mediante EnvironmentFile.

Autenticación

Toda solicitud REST y MCP requiere Authorization: Bearer <MAIL_MCP_API_TOKEN>.

Pruebas

npm test              # run once
npm run test:coverage # run with coverage report

La cobertura cubre los módulos puros/lógicos (lib/schemas.js, lib/accounts.js, lib/webhooks-store.js). lib/mailclient.js y lib/idle-watcher.js se comunican con servidores IMAP/SMTP reales y se ejercitan mediante pruebas manuales de extremo a extremo en lugar de pruebas unitarias — están excluidos de la insignia de cobertura para que no sea engañosa.