Servidor JMAP MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con servidores de correo electrónico JMAP (JSON Meta Application Protocol). Construido con Deno y utilizando la biblioteca cliente @htunnicliff/jmap-jam.

Características

Herramientas de gestión de correo electrónico

• Buscar correos: Busca correos electrónicos con consultas de texto, filtros de remitente/destinatario, rangos de fechas y palabras clave. Todos los filtros se combinan mediante AND.

• Obtener correos: Recupera correos electrónicos específicos por ID con selección de propiedades configurable.

• Obtener hilos: Recupera hilos de correo electrónico (cadenas de conversación).

• Marcar correos: Marca correos como leídos/no leídos, marcados/no marcados.

• Mover correos: Mueve correos entre buzones.

• Eliminar correos: Elimina correos permanentemente.

Gestión de buzones

• Obtener buzones: Lista todos los buzones/carpetas con soporte de jerarquía. Úsalo para encontrar los IDs de buzón necesarios para otras herramientas.

Sincronización incremental

• Obtener cambios de correo: Obtiene los IDs de correos creados, actualizados o eliminados desde un estado anterior (seguimiento de cambios basado en estado).

• Obtener actualizaciones de búsqueda: Obtiene adiciones/eliminaciones dentro de una consulta de búsqueda anterior desde su último queryState.

Composición de correos

• Enviar correo: Redacta y envía nuevos correos con soporte para texto plano y HTML.

• Responder a un correo: Responde a correos existentes con manejo automático de encabezados y soporte para responder a todos.

Capacidades clave

• Cumplimiento total con JMAP RFC 8620/8621 a través de jmap-jam.

• Validación de entrada completa con esquemas Zod.

• Soporte de paginación para todas las operaciones de lista.

• Sincronización incremental basada en estado para un sondeo eficiente.

• Manejo de errores robusto y gestión de conexiones.

• Registro de herramientas basado en capacidades (solo lectura, envío).

• Soporte para TypeScript con tipado fuerte.

Related MCP server: bare-mcp

Instalación

Plugin de Claude Code (Recomendado)

Instalar a través del mercado de plugins:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

Luego, configura las variables de entorno requeridas en la configuración de tu servidor MCP.

Requisitos previos

• Deno v1.40 o posterior.

• Un servidor de correo compatible con JMAP (ej. Cyrus IMAP, Stalwart Mail Server, FastMail).

• Credenciales de autenticación JMAP válidas.

Configuración

Agrega lo siguiente a tu agente de elección:

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Reemplaza api.fastmail.com en --allow-net con el nombre de host de tu servidor JMAP si no usas FastMail.

Uso

Variables de entorno

Herramientas disponibles

get_mailboxes

Lista buzones/carpetas con sus IDs, nombres y metadatos. Llama a esto primero para obtener los IDs de buzón necesarios para search_emails (inMailbox) y move_emails (mailboxId). Nombres comunes: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

Parámetros:

• parentId (opcional): Filtrar por ID de buzón padre.

• limit (opcional): Resultados máximos (1-200, predeterminado: 100).

• position (opcional): Posición inicial para la paginación.

search_emails

Busca correos con filtros. Todos los filtros se combinan mediante AND. Devuelve solo IDs de correo; usa get_emails para obtener el contenido. Los resultados incluyen queryState para la sincronización incremental mediante get_search_updates.

Parámetros:

• query (opcional): Búsqueda de texto en todos los campos.

• body (opcional): Buscar solo en el cuerpo del mensaje.

• from (opcional): Filtrar por dirección de correo del remitente.

• to (opcional): Filtrar por dirección de correo del destinatario.

• subject (opcional): Filtrar por texto del asunto.

• inMailbox (opcional): ID del buzón donde buscar (obtener de get_mailboxes).

• hasKeyword (opcional): Filtrar por palabra clave (ej. $seen, $flagged).

• notKeyword (opcional): Excluir por palabra clave (ej. $seen, $draft).

• allInThreadHaveKeyword (opcional): Todos los correos en el hilo deben tener la palabra clave.

• someInThreadHaveKeyword (opcional): Al menos un correo en el hilo debe tener la palabra clave.

• before (opcional): Solo correos antes de la fecha (fecha y hora ISO 8601).

• after (opcional): Solo correos después de la fecha (fecha y hora ISO 8601).

• limit (opcional): Resultados máximos (1-100, predeterminado: 50).

• position (opcional): Posición inicial para la paginación (predeterminado: 0).

get_emails

Recupera correos específicos por sus IDs. Usa properties para solicitar solo lo que necesitas; obtener todas las propiedades devuelve cargas útiles grandes.

Parámetros:

• ids: Matriz de IDs de correo (1-50 IDs).

• properties (opcional): Propiedades específicas a devolver. Conjuntos recomendados:

  • Resumen: ["id", "subject", "from", "to", "receivedAt", "preview"]

  • Lectura completa: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

  • Nota: Para obtener el contenido del cuerpo, incluye bodyValues Y textBody/htmlBody.

get_threads

Obtiene hilos de correo por sus IDs. Los IDs de hilo provienen de las respuestas de get_emails (propiedad threadId). Devuelve IDs de correo por hilo; usa get_emails en esos IDs para obtener el contenido.

Parámetros:

• ids: Matriz de IDs de hilo (1-20 IDs).

get_email_changes

Obtiene IDs de correos creados, actualizados o eliminados desde un estado anterior. Usa la cadena state de una respuesta de get_emails.

Parámetros:

• sinceState: Cadena de estado de una respuesta anterior de get_emails.

• maxChanges (opcional): Cambios máximos a devolver (1-500).

• fetchEmails (opcional): Obtener automáticamente detalles completos del correo para los IDs cambiados (predeterminado: false).

• properties (opcional): Propiedades a obtener cuando fetchEmails es true.

get_search_updates

Obtiene cambios dentro de una consulta de búsqueda anterior desde su queryState. Debe usar los mismos parámetros de filtro que la llamada original a search_emails.

Parámetros:

• sinceQueryState: queryState de una respuesta anterior de search_emails.

• Todos los parámetros de filtro de search_emails (deben coincidir con la consulta original).

• maxChanges (opcional): Cambios máximos a devolver (1-500).

mark_emails

Marca correos como leídos/no leídos o marcados/no marcados.

Parámetros:

• ids: Matriz de IDs de correo (1-100 IDs).

• seen (opcional): Marcar como leído (true) o no leído (false).

• flagged (opcional): Marcar como marcado (true) o no marcado (false).

move_emails

Mueve correos a un buzón diferente. Usa get_mailboxes para encontrar el ID del buzón de destino.

Parámetros:

• ids: Matriz de IDs de correo (1-100 IDs).

• mailboxId: ID del buzón de destino (obtener de get_mailboxes).

delete_emails

Elimina correos permanentemente (no se puede deshacer). Prefiere mover a la Papelera mediante move_emails para una eliminación recuperable.

Parámetros:

• ids: Matriz de IDs de correo (1-100 IDs).

send_email

Envía un nuevo correo. Requiere textBody o htmlBody (o ambos).

Parámetros:

• to: Matriz de destinatarios (name opcional, email requerido).

• cc (opcional): Matriz de destinatarios CC.

• bcc (opcional): Matriz de destinatarios BCC.

• subject: Asunto del correo.

• textBody (opcional): Cuerpo de texto plano.

• htmlBody (opcional): Cuerpo HTML.

• identityId (opcional): ID de identidad JMAP desde el cual enviar (usa el predeterminado del servidor si se omite).

reply_to_email

Responde a un correo existente. Establece automáticamente To/CC, el prefijo de asunto Re: y los encabezados de hilo (In-Reply-To, References).

Parámetros:

• emailId: ID del correo al que responder.

• replyAll (opcional): Incluir a todos los destinatarios originales (predeterminado: false).

• subject (opcional): Asunto de respuesta personalizado (predeterminado a Re: <original>).

• textBody (opcional): Cuerpo de texto plano.

• htmlBody (opcional): Cuerpo HTML.

• identityId (opcional): ID de identidad JMAP desde el cual enviar (usa el predeterminado del servidor si se omite).

Compatibilidad del servidor JMAP

Este servidor debería funcionar con cualquier servidor de correo compatible con JMAP, incluyendo:

• Cyrus IMAP 3.0+.

• Stalwart Mail Server.

• FastMail (comercial).

• Apache James (con soporte JMAP).

Desarrollo

Ejecución en desarrollo

just watch          # Run with file watching
just start          # Run without watching

Pruebas

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

Arquitectura

El servidor está construido usando:

• Deno: Entorno de ejecución moderno de JavaScript/TypeScript.

• @modelcontextprotocol/sdk: Marco de trabajo del servidor MCP.

• jmap-jam: Cliente JMAP ligero y tipado.

• Zod: Validación de tipos en tiempo de ejecución.

Seguridad

• Toda la entrada se valida usando esquemas Zod.

• Las variables de entorno se utilizan para configuraciones sensibles.

• No se registran ni exponen secretos en las respuestas.

• Sigue las mejores prácticas de seguridad de JMAP.

Contribución

1. Haz un fork del repositorio.

2. Crea una rama de características.

3. Realiza cambios siguiendo el estilo de programación funcional.

4. Prueba tus cambios exhaustivamente.

5. Envía una solicitud de extracción (pull request).

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Proyectos relacionados

• jmap-jam - Biblioteca cliente JMAP.

• Model Context Protocol - Especificación MCP.

• JMAP RFC 8620 - Protocolo central JMAP.

• JMAP RFC 8621 - JMAP para correo.