Email Processing

Un servidor de procesamiento de correos electrónicos que utiliza MongoDB para búsqueda semántica y SQLite para almacenamiento y recuperación eficientes.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Email Processing

Un servidor MCP multiplataforma que procesa correos electrónicos de Microsoft Outlook, genera embeddings vectoriales usando Ollama y proporciona capacidades de búsqueda semántica. Funciona en Windows, macOS y cualquier plataforma mediante la API de Microsoft Graph.

El servidor cumple con la especificación del Model Context Protocol (MCP) 2025-06-18 y usa el SDK oficial de MCP.

Características

Capacidades principales

Procesa correos de Outlook con filtrado por rango de fechas
Almacena correos en una base de datos SQLite con gestión adecuada de conexiones
Genera embeddings vectoriales usando Ollama (nomic-embed-text)
Búsqueda semántica en el contenido de los correos mediante el almacén vectorial de MongoDB
Soporte multi-buzón y multi-cuenta
Soporte para las carpetas de Bandeja de entrada, Elementos enviados y, opcionalmente, Elementos eliminados

Soporte multiplataforma

Windows: Automatización COM nativa de Outlook mediante pywin32
macOS: Integración con AppleScript para Outlook para Mac
Cualquier plataforma: API de Microsoft Graph para acceso basado en la nube (Windows, macOS, Linux, contenedores)

Cumplimiento de MCP 2025-06-18

Resultados estructurados de herramientas: Las herramientas devuelven modelos Pydantic correctamente tipados y validados
Transporte HTTP: Admite transportes STDIO y HTTP (Streamable HTTP)
Negociación de protocolo: Declara la versión del protocolo durante el handshake
Metadatos mejorados: Títulos y descripciones de herramientas para una mejor integración con la interfaz de usuario

Herramientas disponibles (12+)

Categoría	Herramientas
Procesamiento de correos	`process_emails`
Búsqueda y análisis	`search_emails`, `analyze_email_sentiment`, `find_actionable_items`
Exportación de datos	`export_email_data` (CSV, JSON, HTML, Excel)
Gestión de carpetas	`list_outlook_folders`, `get_folder_statistics`, `organize_emails_by_rules`
Gestión de contactos	`extract_contacts`
Estadísticas	`get_email_statistics`, `check_data_consistency`

Requisitos previos

Requeridos (todas las plataformas)

Python 3.10 o superior
Ollama ejecutándose localmente con el modelo nomic-embed-text
Servidor MongoDB (para almacenar embeddings)

Requisitos específicos por plataforma

Plataforma	Requisito
Windows	Microsoft Outlook instalado + pywin32
macOS	Microsoft Outlook para Mac instalado
Graph API	Registro de aplicación de Azure AD con permiso Mail.Read

Instalación

1. Instalar uv (si aún no está instalado)

pip install uv

2. Crear y activar el entorno virtual

uv venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. Instalar dependencias

Instalación principal (requerida):

uv pip install -e .

Extras específicos por plataforma:

# Windows (adds pywin32 for COM automation)
uv pip install -e ".[windows]"

# Graph API support (cross-platform cloud access)
uv pip install -e ".[graph]"

# All optional dependencies
uv pip install -e ".[all]"

4. Instalar el modelo de embeddings de Ollama

ollama pull nomic-embed-text

5. (Solo Graph API) Registrar la aplicación de Azure AD

Si usas la API de Microsoft Graph, debes registrar una aplicación en Azure AD:

Ve a Azure Portal → Azure Active Directory → Registros de aplicaciones
Haz clic en "Nuevo registro"
Nombra tu aplicación y selecciona "Solo cuentas en este directorio organizativo"
Después de la creación, anota el ID de aplicación (cliente) y el ID de directorio (inquilino)
Ve a "Certificados y secretos" → "Nuevo secreto de cliente" → anota el valor del secreto
Ve a "Permisos de API" → "Agregar un permiso" → "Microsoft Graph" → "Permisos de aplicación"
Agrega: Mail.Read, User.Read.All (para la detección de múltiples cuentas)
Haz clic en "Conceder consentimiento de administrador"

Configuración

Agrega el servidor a tu archivo de configuración de Claude for Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Variables de entorno

Variable	Descripción	Requerida
`MONGODB_URI`	Cadena de conexión de MongoDB	Sí
`SQLITE_DB_PATH`	Ruta al archivo de base de datos SQLite	Sí
`EMBEDDING_BASE_URL`	URL del servidor de Ollama (predeterminado: http://localhost:11434)	No
`EMBEDDING_MODEL`	Nombre del modelo de embeddings (predeterminado: nomic-embed-text)	No
`COLLECTION_NAME`	Nombre de la colección de MongoDB	Sí
`PROCESS_DELETED_ITEMS`	Procesar la carpeta de Elementos eliminados (predeterminado: "false")	No
`OUTLOOK_PROVIDER`	Proveedor: `auto`, `windows`, `mac`, `graph` (predeterminado: "auto")	No
`LOCAL_TIMEZONE`	Zona horaria para fechas (predeterminado: "UTC", p. ej., "America/Chicago")	No

Variables de Graph API (requeridas cuando OUTLOOK_PROVIDER=graph):

Variable	Descripción
`GRAPH_CLIENT_ID`	ID de aplicación (cliente) de Azure AD
`GRAPH_CLIENT_SECRET`	Secreto de cliente de Azure AD
`GRAPH_TENANT_ID`	ID de inquilino de Azure AD
`GRAPH_USER_EMAILS`	Buzones: lista separada por comas o "All" para autodetección

Configuración de Windows (automatización COM)

Usa automatización COM nativa de Outlook mediante pywin32.

{
  "mcpServers": {
    "outlook-email": {
      "command": "C:/path/to/.venv/Scripts/python",
      "args": ["C:/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "windows",
        "LOCAL_TIMEZONE": "America/Chicago"
      }
    }
  }
}

Configuración de macOS (AppleScript)

Usa AppleScript para comunicarse con Outlook para Mac.

{
  "mcpServers": {
    "outlook-email": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "/path/to/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "mac",
        "LOCAL_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Configuración de Graph API (multiplataforma)

Funciona en cualquier plataforma con credenciales de Azure AD. Admite uno o varios buzones.

Buzón único o buzones específicos:

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com"
      }
    }
  }
}

Todos los buzones del inquilino (autodetección):

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "All"
      }
    }
  }
}

Autodetección de proveedor

Cuando OUTLOOK_PROVIDER está configurado como auto (predeterminado), el servidor selecciona automáticamente el mejor proveedor:

Plataforma	Proveedor seleccionado automáticamente
Windows	`windows` (automatización COM)
macOS	`mac` (AppleScript)
Linux/Otros	`graph` (requiere configuración de Azure AD)

Transporte HTTP (compatible con 2025-06-18)

Para el transporte HTTP, ejecuta el servidor con la bandera --http:

python src/mcp_server.py --http

Esto iniciará el servidor en http://localhost:8000/mcp con cumplimiento completo del protocolo 2025-06-18, incluyendo:

Negociación de la versión del protocolo
Esquemas de salida estructurada
Validación de cabeceras HTTP
Manejo adecuado de errores

El transporte HTTP admite modos de operación con estado y sin estado.

Herramientas disponibles

1. process_emails

Procesa correos de un rango de fechas especificado y devuelve resultados estructurados:

Entrada:

{
  "start_date": "2024-01-01",    # ISO format date (YYYY-MM-DD)
  "end_date": "2024-02-15",      # ISO format date (YYYY-MM-DD)
  "mailboxes": ["All"]           # List of mailbox names or ["All"] for all mailboxes
}

Salida (estructurada):

{
  "success": true,
  "processed_count": 150,
  "retrieved_count": 200,
  "stored_count": 180,
  "failed_count": 20,
  "message": "Successfully processed 150 emails (retrieved: 200, stored: 180, failed: 20)",
  "error": null
}

La herramienta:

Se conectará a los buzones de Outlook especificados
Recuperará correos de las carpetas de Bandeja de entrada y Elementos enviados (y Elementos eliminados si está habilitado)
Almacenará correos en la base de datos SQLite
Generará embeddings usando Ollama
Almacenará embeddings en MongoDB para búsqueda semántica
Devolverá resultados estructurados con estadísticas detalladas

Ejemplo de uso en Claude

"Process emails from February 1st to February 17th from all mailboxes"

Arquitectura

Diseño de conectores basado en proveedores

El servidor usa una abstracción basada en proveedores para el acceso multiplataforma a correos:

src/connectors/
├── base.py               # OutlookConnectorBase (abstract interface)
├── factory.py            # create_connector() with auto-detection
├── windows_connector.py  # Windows COM via pywin32
├── mac_connector.py      # macOS AppleScript via osascript
└── graph_connector.py    # Microsoft Graph API (cross-platform)

Todos los conectores implementan la misma interfaz y devuelven objetos EmailMetadata estandarizados independientemente de la plataforma.

Arquitectura de doble base de datos

El servidor usa un enfoque de almacenamiento híbrido:

Base de datos SQLite:

Almacenamiento principal de correos y metadatos
Capacidades de búsqueda de texto completo
Seguimiento del estado de procesamiento
Filtrado por rango de fechas y carpeta
Consultas estructuradas rápidas

MongoDB:

Almacenamiento de embeddings vectoriales (768 dimensiones)
Búsqueda de similitud semántica
Metadatos almacenados junto con los embeddings
Habilita la búsqueda impulsada por IA

Manejo de errores

El servidor proporciona mensajes de error detallados para problemas comunes:

Formatos de fecha no válidos
Problemas de conexión con Outlook
Errores de MongoDB
Fallos en la generación de embeddings con lógica de reintento
Errores de almacenamiento de SQLite
Problemas de conexión con el servidor de Ollama con reintentos automáticos

Gestión de recursos

El servidor implementa una gestión adecuada de recursos para prevenir problemas:

Las conexiones de base de datos (SQLite y MongoDB) se mantienen abiertas durante la vida útil del servidor para evitar errores de "No se puede operar en una base de datos cerrada"
Las conexiones solo se cierran cuando el servidor se apaga, mediante un manejador atexit
Se usan destructores y administradores de contexto como respaldo para garantizar que las conexiones se cierren cuando los objetos se recolectan como basura
La gestión de conexiones está diseñada para equilibrar el uso de recursos con la fiabilidad operativa
Lógica de reintento robusta para servicios externos como Ollama para manejar problemas temporales de conexión

Cumplimiento de MCP 2025-06-18

Este servidor se ha actualizado para cumplir con la especificación MCP 2025-06-18:

Características del protocolo

Versión del protocolo: Declara protocolVersion: "2025-06-18" durante el handshake
Salida estructurada: Todas las herramientas devuelven modelos Pydantic tipados y validados
Transporte HTTP: Admite Streamable HTTP con validación adecuada de cabeceras
Metadatos de herramientas: Descripciones mejoradas de herramientas con títulos y esquemas
Manejo de errores: Respuestas de error estructuradas con información detallada

Soporte de transporte

STDIO: Comunicación tradicional stdin/stdout (predeterminado)
HTTP: Streamable HTTP en localhost:8000/mcp con validación de cabeceras
Cabeceras de protocolo: Valida las cabeceras MCP-Protocol-Version y Origin
JSON-RPC de mensaje único: Sin soporte de solicitudes por lotes según la especificación 2025-06-18

Salida estructurada

La herramienta process_emails devuelve un ProcessEmailsResult estructurado con:

success: Booleano que indica el éxito de la operación
processed_count: Número de correos procesados correctamente
retrieved_count: Total de correos recuperados de Outlook
stored_count: Número de correos almacenados en SQLite
failed_count: Número de correos que fallaron en el procesamiento
message: Mensaje de estado legible por humanos
error: Detalles del error si la operación falló

Notas de seguridad

El servidor solo procesa correos de buzones especificados
Todos los datos se almacenan localmente (SQLite) y en MongoDB
Sin llamadas API externas excepto al servidor local de Ollama (y Microsoft Graph si se usa ese proveedor)
Requiere aprobación explícita del usuario para el procesamiento de correos
No se exponen datos sensibles de correos a través de la interfaz MCP
El transporte HTTP se vincula solo a localhost por seguridad
Graph API usa el flujo de credenciales de cliente OAuth 2.0 con Azure AD
Almacena las credenciales de Azure AD de forma segura (variables de entorno, no en el código)

Depuración

Si encuentras problemas:

Verifica que los correos se procesaron correctamente (revisa la respuesta de process_emails)
Asegúrate de que el servidor de Ollama esté ejecutándose para la generación de embeddings
Comprueba que la base de datos SQLite sea accesible
Verifica que la conexión de MongoDB funcione correctamente
Usa la herramienta check_data_consistency para verificar la sincronización de SQLite/MongoDB

Depuración específica por plataforma

Windows:

Asegúrate de que Outlook esté ejecutándose y sea accesible
Comprueba que pywin32 esté instalado: pip show pywin32
Verifica que la automatización COM funcione: python -c "import win32com.client; print('OK')"

macOS:

Asegúrate de que Outlook para Mac esté instalado (no solo la aplicación web "New Outlook")
Prueba el acceso a AppleScript: osascript -e 'tell application "Microsoft Outlook" to get name'
Concede permiso a Terminal/IDE en Preferencias del Sistema → Seguridad y privacidad → Automatización

Graph API:

Verifica que la aplicación de Azure AD tenga los permisos correctos (Mail.Read, User.Read.All)
Comprueba que se haya concedido el consentimiento de administrador
Prueba la adquisición de tokens: las credenciales se registran al inicio
Verifica que GRAPH_USER_EMAILS esté configurado correctamente ("All" o correos separados por comas)

Limitaciones de la plataforma

Plataforma	Limitación
Windows	Requiere la aplicación de escritorio de Outlook ejecutándose
macOS	"New Outlook" puede tener soporte limitado de AppleScript; usa Graph API como alternativa
Graph API	Requiere configuración de Azure AD; se aplica un rango máximo de fechas de 30 días
Todas	Rango máximo de procesamiento de 30 días por solicitud

Próximas funciones

Resumen de correos mediante LLM
Categorización automática de correos
Informes de correos personalizables
Redacción de respuestas de correo en Outlook
Sugerencias de reglas de Outlook
Opciones ampliadas de base de datos con integración de Neo4j y ChromaDB