email-client-mcp

Email MCP Server

Un servidor MCP (Model Context Protocol) para interactuar con cuentas de email mediante IMAP. El servidor funciona en modo stdio y se configura completamente mediante variables de entorno.

Instalación y Setup

• Instala las dependencias:

pnpm install

• Compila el proyecto:

pnpm run build

Configuración

El servidor se configura exclusivamente mediante variables de entorno. Configura las siguientes variables antes de ejecutarlo:

Variables Requeridas

• IMAP_HOST - Servidor IMAP (ej: imap.gmail.com)
• IMAP_USER - Tu dirección de email
• IMAP_PASS - Contraseña de tu email o app password

Variables Opcionales

• IMAP_PORT - Puerto del servidor IMAP (default: 993)
• IMAP_SECURE - Usar conexión segura (default: true)
• IMAP_REJECT_UNAUTHORIZED - Rechazar certificados autofirmados (default: false)

Integración con Claude Desktop

Agrega esta configuración a tu archivo MCP de Claude Desktop:

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["email-client-mcp"],
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_USER": "[e-mail]", 
        "IMAP_PASS": "tu_app_password"
      }
    }
  }
}

Ejemplo para Gmail

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["email-client-mcp"],
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "IMAP_USER": "[e-mail]",
        "IMAP_PASS": "tu_app_password",
        "IMAP_SECURE": "true"
      }
    }
  }
}

Uso Directo (Desarrollo)

Para pruebas locales puedes ejecutar directamente:

# Con variables de entorno
IMAP_HOST="imap.gmail.com" IMAP_USER="[e-mail]" IMAP_PASS="tu_password" npx email-client-mcp

# O usando un archivo .env (no recomendado para producción)
echo "IMAP_HOST=imap.gmail.com
IMAP_USER=[e-mail]  
IMAP_PASS=tu_password" > .env
npx email-client-mcp

Herramientas Disponibles

Gestión de Conexión (Auto-conecta usando variables de entorno)

• connect_imap - Conexión IMAP manual (opcional)
• disconnect_imap - Desconectar del servidor IMAP
• get_connection_status - Verificar estado de conexión
• get_env_config - Mostrar configuración (contraseñas enmascaradas)

Gestión de Carpetas

• list_mailboxes - Listar carpetas disponibles
• select_mailbox - Seleccionar carpeta de trabajo

Operaciones de Email (IMAP)

• get_messages - Obtener mensajes paginados de una carpeta
• get_unread_messages - Obtener solo mensajes no leídos
• get_message_content - Obtener contenido completo de un mensaje

Operaciones de Envío (SMTP)

• send_email - Enviar nuevos emails con soporte para adjuntos
• reply_to_message - Responder mensajes existentes con contexto

Búsqueda Unificada

• search_messages - Búsqueda integral con todas las opciones:
  • Búsquedas rápidas: mensajes recientes, mensajes grandes
  • Búsquedas de texto: remitente, destinatario, asunto, contenido
  • Filtros de fecha: desde/hasta fechas específicas
  • Filtros de estado: leído/no leído, marcado, respondido
  • Filtros de tamaño: mayor/menor que tamaño especificado
  • Opciones avanzadas: consultas IMAP raw, ordenamiento, selección de carpeta

Herramientas de Depuración

• debug_search_simple - Probar funcionalidad básica de búsqueda IMAP
• check_uid_exists - Verificar si existe un UID específico
• show_recent_uids - Mostrar UIDs recientes para depuración

Capacidades de Búsqueda Unificada

La herramienta search_messages proporciona funcionalidad completa de búsqueda:

• Búsquedas rápidas: recent_days (últimos N días), large_messages_mb (mensajes > N MB)
• Búsquedas de texto: remitente, destinatario, asunto, contenido del cuerpo
• Filtros de fecha: desde/hasta fechas específicas (formato YYYY-MM-DD)
• Filtros de estado: leído/no leído, marcado, respondido (true/false)
• Filtros de tamaño: mensajes mayores/menores a un tamaño específico (KB)
• Opciones avanzadas: consultas IMAP raw, ordenamiento (fecha/tamaño/asunto), selección de carpeta
• Control de resultados: límite de resultados, orden (asc/desc)

Todos los resultados se devuelven en formato JSON estructurado para fácil procesamiento por agentes de IA.

Desarrollo

# Modo desarrollo
pnpm run dev

# Compilar
pnpm run build

# Ejecutar compilado
pnpm run start