Outlook Assistant

Outlook Assistant

Servidor MCP para correo, calendario y contactos de Outlook: permite que tu asistente de IA gestione tu bandeja de entrada directamente desde la conversación.

Outlook Assistant conecta asistentes de IA a tu cuenta de Microsoft Outlook mediante el Model Context Protocol. Pide a tu asistente de IA que busque en tu bandeja de entrada, envíe correos, programe reuniones, gestione contactos y configure los ajustes del buzón, sin salir de la conversación. Funciona con Claude, Cursor, Windsurf y cualquier cliente compatible con MCP.

Funciona con cuentas personales de Outlook.com y cuentas de Microsoft 365 de trabajo o escuela.

_{Buscar en la bandeja → leer y resumir → redactar una respuesta, todo desde la conversación}

Lo que puedes hacer

• 📨 Buscar y leer correos — encuentra mensajes por remitente, asunto, fecha o palabras clave; lee hilos completos con agrupación por conversación; marca, mueve, exporta o categoriza varios correos a la vez
• 🛡️ Enviar correos con controles de seguridad — vista previa en seco, avisos previos al envío (fuera de oficina, buzón lleno, restricciones de entrega), límite de frecuencia por sesión y lista de destinatarios permitidos para evitar errores
• ✏️ Redactar correos para revisión — crea, actualiza y envía borradores; responde y reenvía como borradores; obtén una vista previa antes de guardar con el modo de ensayo
• 📅 Gestionar tu calendario — consulta próximos eventos, programa reuniones con asistentes, rechaza o cancela invitaciones
• 📦 Exportar correos — guarda mensajes individuales en Markdown, EML, JSON o CSV; exporta hilos completos de conversación a MBOX o HTML; exporta por lotes los resultados de búsqueda en una sola llamada
• 🔍 Investigar cabeceras de correo — acceso completo a cabeceras sin procesar (DKIM, SPF, DMARC, cadena de entrega, X-Mailer, X-Originating-IP) para investigación de phishing y revisión de cumplimiento
• 🗂️ Organizar tu bandeja de entrada — crea carpetas anidadas (direccionables por ruta), configura reglas de bandeja, codifica con categorías, gestiona la Bandeja de entrada prioritarios; todo funciona en conjunto para una automatización completa de la bandeja
• 🔄 Seguimiento de cambios en la bandeja — la sincronización incremental detecta correos nuevos, modificados y eliminados desde tu última comprobación, con tokens para sondeo incremental
• 👥 Gestionar contactos — busca en tu libreta de contactos y en el directorio de la organización, crea y actualiza registros de contacto
• ⚙️ Configurar ajustes — establece respuestas automáticas de fuera de oficina, horario laboral y zona horaria
• 📬 Acceder a buzones compartidos — lee bandejas de equipos y cuentas de servicio (Microsoft 365)
• 🏢 Buscar salas de reuniones — busca por edificio, planta, capacidad, equipos audiovisuales y accesibilidad para sillas de ruedas (Microsoft 365)

¿Por qué Outlook Assistant?

Características

22 herramientas en total, consolidadas de 55 para un rendimiento óptimo de IA. Consulta la Referencia de herramientas para obtener detalles completos de los parámetros.

Formatos de exportación

El soporte de formatos varía según target:

Exporta correos individuales, resultados de búsqueda o hilos completos de conversación: usa target=messages con una consulta de búsqueda (o el atajo query) para exportar por lotes sin recopilar IDs manualmente.

Compatibilidad de cuentas

Outlook Assistant funciona tanto con cuentas personales de Microsoft como con cuentas de trabajo o escuela, pero algunas funciones se comportan de manera diferente:

Nota: En cuentas personales, la API $search de Microsoft tiene soporte limitado para consultas de texto libre. Outlook Assistant lo maneja automáticamente con búsqueda progresiva: si tu consulta no devuelve resultados, recurre a filtros OData, filtros booleanos y listado de mensajes recientes para encontrar tus correos. Para obtener los resultados más directos en cuentas personales, usa los parámetros de filtro estructurado (from, subject, to, receivedAfter).

Qué hace que esto sea diferente

• Búsqueda progresiva: en cuentas donde la API $search de Microsoft es limitada, Outlook Assistant recurre automáticamente a hasta 4 estrategias de búsqueda para encontrar tus correos. La mayoría de los envoltorios de Graph API fallan silenciosamente; este se adapta.
• Forense de correo: acceso a cabeceras sin procesar para DKIM, SPF, DMARC, cadena de entrega, X-Mailer, X-Originating-IP y puntuaciones de spam. Devuelve los datos completos para que puedas investigar phishing, auditar cumplimiento o rastrear problemas de entrega. (El veredicto automático está en la hoja de ruta; hoy los datos se muestran y se analizan en la conversación).
• Sincronización incremental: el monitoreo incremental de la bandeja devuelve solo lo que ha cambiado desde tu última comprobación, con tokens para sondeo continuo. Diseñado para flujos de trabajo de agentes que necesitan vigilar un buzón.
• Operaciones por lotes: marca, mueve, exporta o categoriza varios correos en una sola llamada. La exportación impulsada por búsqueda te permite exportar resultados por lotes sin recopilar IDs manualmente.
• Inteligencia previa al envío: verifica destinatarios para detectar fuera de oficina, buzón lleno, restricciones de entrega y estado de moderación antes de enviar; ningún otro servidor MCP de Outlook ofrece esto.
• Automatización compuesta: reglas, categorías, carpetas y Bandeja de entrada prioritarios funcionan juntos. Configura la gestión completa de tu bandeja a través de tu asistente de IA en una sola conversación.

Seguridad y eficiencia de tokens

Outlook Assistant está diseñado con principios de seguridad primero para el acceso a correo impulsado por IA:

Salvaguardas para acciones destructivas: cada herramienta incluye anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint) para que los clientes de IA puedan aprobar automáticamente lecturas seguras y pedir confirmación para operaciones destructivas como enviar correo o eliminar eventos.

Protecciones de envío de correo: la herramienta send-email incluye:

• Avisos de correo previos al envío (checkRecipients: true): verifica destinatarios para detectar fuera de oficina o buzón lleno, restricciones de entrega antes de enviar
• Modo de vista previa (dryRun: true): previsualiza los correos redactados sin enviarlos
• Límite de frecuencia por sesión: configurable mediante OUTLOOK_MAX_EMAILS_PER_SESSION (por defecto: ilimitado)
• Lista de destinatarios permitidos: restringe el envío a direcciones/dominios aprobados mediante OUTLOOK_ALLOWED_RECIPIENTS

Configuración recomendada: activa ambos cinturones de seguridad en tu .mcp.json desde el primer día. Están desactivados por defecto; auth action=about informa de su estado e imprime una sugerencia de configuración cuando no están establecidos. Consulta .mcp.json.example para una plantilla lista para copiar y pegar.

"env": {
  "OUTLOOK_CLIENT_ID": "…",
  "OUTLOOK_CLIENT_SECRET": "…",
  "OUTLOOK_MAX_EMAILS_PER_SESSION": "10",
  "OUTLOOK_ALLOWED_RECIPIENTS": "your-domain.com,trusted@example.com"
}

Protecciones para borradores: la herramienta draft comparte los controles de seguridad de send-email: vista previa en seco, lista de destinatarios permitidos, validación de avisos de correo y limitación de frecuencia. La acción send comparte el contador de límite de frecuencia de send-email, evitando la evasión mediante la ruta de borrador-luego-envío.

Arquitectura optimizada en tokens: las herramientas se consolidan mediante el enfoque STRAP (Patrón de Acción, Recurso y Herramienta Única). 22 herramientas en lugar de 55 reduce la sobrecarga por turno en ~11 000 tokens (~64 %), manteniendo más del contexto del IA disponible para tu conversación real. Menos herramientas también significa que el IA selecciona la herramienta correcta con mayor precisión; la investigación muestra que la selección de herramientas se degrada más allá de ~40 herramientas.

Importante: estas salvaguardas son medidas de defensa en profundidad que reducen el riesgo, pero no garantizan contra acciones no intencionadas. El acceso a tu correo impulsado por IA es intrínsecamente sensible: revisa siempre las llamadas a herramientas antes de aprobarlas, especialmente los envíos y eliminaciones. Ninguna salvaguarda automatizada es infalible y sigues siendo responsable de las acciones realizadas a través de tu buzón.

Inicio rápido

1. Instalación

npm install -g @littlebearapps/outlook-assistant

O ejecútalo directamente sin instalar:

npx @littlebearapps/outlook-assistant

2. Registrar una aplicación de Azure

Necesitas un registro de aplicación de Microsoft Azure para autenticarte. Consulta la Guía de configuración de Azure para obtener un recorrido detallado (incluida la creación de una cuenta de Azure por primera vez) o, si ya lo has hecho antes:

1. Crea un nuevo registro de aplicación en portal.azure.com
2. Añade permisos delegados de Microsoft Graph (Correo, Calendario, Contactos)
3. Crea un secreto de cliente y copia el Valor (no el ID del secreto)
4. En Autenticación > Agregar una plataforma > Aplicaciones móviles y de escritorio — marca la URI nativeclient
5. Habilita "Permitir flujos de cliente públicos" en Autenticación > Configuración avanzada
6. (Opcional) Establece la URI de redirección a http://localhost:3333/auth/callback — solo es necesaria para el flujo de autenticación por navegador

3. Configura tu cliente MCP

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

claude mcp add outlook -- npx @littlebearapps/outlook-assistant

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

4. Autentícate

1. Inicia el servidor de autenticación: outlook-assistant-auth (o npx @littlebearapps/outlook-assistant-auth)
2. En tu asistente de IA, usa la herramienta auth con action=authenticate para obtener una URL de OAuth
3. Abre la URL, inicia sesión con tu cuenta de Microsoft y concede permisos
4. Los tokens se guardan localmente y se actualizan automáticamente

Nota: El servidor de autenticación necesita las variables de entorno OUTLOOK_CLIENT_ID y OUTLOOK_CLIENT_SECRET. La configuración de "env" de tu cliente MCP solo se aplica al proceso del servidor MCP — cuando ejecutes el servidor de autenticación por separado, asegúrate de que estas estén definidas en un archivo .env o exportadas en tu shell.

Instalación

Requisitos previos

• Node.js 18.0.0 o superior
• npm (incluido con Node.js)
• Cuenta de Azure para el registro de aplicación (el nivel gratuito funciona)

Desde npm (recomendado)

npm install -g @littlebearapps/outlook-assistant

Desde el código fuente

git clone https://github.com/littlebearapps/outlook-assistant.git
cd outlook-assistant
npm install

Registro de aplicación en Azure

¿Es tu primera vez con Azure? La Guía de configuración de Azure cubre todo, desde crear una cuenta hasta tu primera autenticación, incluyendo la configuración de facturación y los errores más comunes.

Crear la aplicación

1. Abre Azure Portal
2. Inicia sesión con una cuenta personal o profesional de Microsoft
3. Busca Registros de aplicaciones y haz clic en Nuevo registro
4. Introduce un nombre (p. ej. "Outlook Assistant Server")
5. Selecciona Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft
6. Establece la URI de redirección: plataforma Web, URI http://localhost:3333/auth/callback
7. Haz clic en Registrar
8. Copia el ID de aplicación (cliente)

Añadir permisos

1. Ve a Permisos de API > Agregar un permiso > Microsoft Graph > Permisos delegados
2. Añade estos permisos obligatorios:
   • offline_access — tokens de actualización entre sesiones
   • User.Read — perfil básico
   • Mail.Read, Mail.ReadWrite, Mail.Send — operaciones de correo
   • Calendars.Read, Calendars.ReadWrite — operaciones de calendario
   • Contacts.Read, Contacts.ReadWrite — gestión de contactos
   • MailboxSettings.ReadWrite — configuración, respuestas automáticas, categorías
   • People.Read — búsqueda de personas
3. Opcionalmente, añade permisos solo de organización (solo cuentas profesionales o educativas):
   • Mail.Read.Shared — acceso a buzones compartidos
   • Place.Read.All — búsqueda de salas de reuniones (requiere consentimiento del administrador)
4. Haz clic en Agregar permisos

Crear un secreto de cliente

1. Ve a Certificados y secretos > Nuevo secreto de cliente
2. Introduce una descripción y selecciona la caducidad
3. Haz clic en Agregar
4. Copia el Valor del secreto inmediatamente — no podrás verlo de nuevo. Usa el Valor, no el ID del secreto.

Configuración

Variables de entorno

Crea un archivo .env a partir del ejemplo:

cp .env.example .env

Edítalo con tus credenciales de Azure:

OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
USE_TEST_MODE=false

Nota: El servidor también acepta MS_CLIENT_ID y MS_CLIENT_SECRET por compatibilidad con versiones anteriores.

Anulaciones opcionales (v3.8.0+) — consulta .env.example para ver la lista completa con ejemplos comentados:

Configuración del cliente MCP

Consulta Inicio rápido — Configura tu cliente MCP más arriba para las configuraciones de Claude Desktop, Claude Code, Cursor y Windsurf.

Si se instaló desde el código fuente, usa node en lugar de npx:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/path/to/outlook-assistant/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

Flujo de autenticación

Flujo de código de dispositivo (predeterminado — recomendado)

No se necesita servidor de autenticación. Funciona en cualquier entorno, incluidos los remotos o sin interfaz gráfica.

1. Pide a tu asistente de IA que se autentique (llama a la herramienta auth con action=authenticate)
2. Visita la URL mostrada (microsoft.com/devicelogin) desde cualquier navegador, cualquier dispositivo
3. Introduce el código, inicia sesión con tu cuenta de Microsoft y concede permisos
4. Indica a tu asistente de IA que complete la autenticación (llama a auth con action=device-code-complete)
5. Los tokens se guardan en ~/.outlook-assistant-tokens.json y se actualizan automáticamente

Requisito previo: Habilita "Permitir flujos de cliente públicos" en Azure Portal > tu aplicación > Autenticación > Configuración avanzada.

Reinicios del servidor (v3.7.2+): El estado del código de dispositivo se guarda en ~/.outlook-assistant-pending-auth.json, por lo que device-code-complete funciona incluso si el servidor MCP se reinicia entre los pasos 1 y 4 (p. ej., puente Untether/Telegram, cambios de sesión en Claude Desktop).

Flujo de redirección por navegador (alternativa)

Para desarrollo local o si prefieres el flujo OAuth tradicional:

npm run auth-server

Esto inicia un servidor local en el puerto 3333 para gestionar la devolución de llamada de OAuth.

1. En tu asistente de IA, usa la herramienta auth con action=authenticate, method=browser
2. Abre la URL proporcionada en tu navegador
3. Inicia sesión y concede permisos — los tokens se guardan automáticamente

Nota: El servidor de autenticación lee OUTLOOK_CLIENT_ID y OUTLOOK_CLIENT_SECRET de las variables de entorno. La configuración de "env" de tu cliente MCP solo se aplica al proceso del servidor MCP, no a un servidor de autenticación iniciado por separado.

Estructura de directorios

outlook-assistant/
├── index.js                 # Main entry point (22 tools)
├── config.js                # Configuration settings
├── outlook-auth-server.js   # OAuth server (port 3333)
├── auth/                    # Authentication module (1 tool)
├── email/                   # Email module (7 tools)
│   ├── mail-tips.js         # Pre-send recipient validation
│   ├── headers.js           # Email header retrieval
│   ├── mime.js              # Raw MIME/EML content
│   ├── conversations.js     # Thread listing/export
│   ├── attachments.js       # Attachment operations
│   └── ...
├── calendar/                # Calendar module (3 tools)
├── contacts/                # Contacts module (2 tools)
├── categories/              # Categories module (3 tools)
├── settings/                # Settings module (1 tool)
├── folder/                  # Folder module (1 tool)
├── rules/                   # Rules module (1 tool)
├── advanced/                # Advanced module (2 tools)
└── utils/
    ├── graph-api.js         # Microsoft Graph API client (includes $batch)
    ├── safety.js            # Rate limiting, recipient allowlist, dry-run
    ├── odata-helpers.js     # OData query building
    ├── field-presets.js     # Token-efficient field selections
    ├── response-formatter.js # Verbosity levels
    └── mock-data.js         # Test mode data

Solución de problemas

"Cannot find module '@modelcontextprotocol/sdk/server/index.js'"

npm install

"EADDRINUSE: address already in use :::3333"

npx kill-port 3333
npm run auth-server

"Invalid client secret" (AADSTS7000215)

Estás usando el ID del secreto en lugar del Valor del secreto. Ve a Azure Portal > Certificados y secretos y copia la columna Valor.

La URL de autenticación no funciona

Si usas el flujo por navegador: inicia primero el servidor de autenticación con npm run auth-server. Si usas el flujo de código de dispositivo: visita microsoft.com/devicelogin en su lugar.

Código de dispositivo "invalid_client"

Habilita "Permitir flujos de cliente públicos" en Azure Portal > Registros de aplicaciones > Autenticación > Configuración avanzada.

La actualización de tokens falla después de ~60 minutos (autenticación por código de dispositivo)

Corregido en v3.7.2. Las versiones anteriores enviaban client_secret en las solicitudes de actualización de tokens para la autenticación por código de dispositivo, lo que Microsoft rechaza para los flujos de cliente públicos. Actualiza a v3.7.2+ o vuelve a autenticarte.

Respuestas de API vacías

Comprueba el estado de autenticación con la herramienta auth (acción=status). Es posible que los tokens hayan caducado; vuelve a autenticarte si es necesario.

Desarrollo

Ejecutar pruebas

npm test                     # Jest unit tests
npm run inspect              # MCP Inspector (interactive)

Modo de prueba

Ejecuta con datos simulados (sin llamadas reales a la API):

USE_TEST_MODE=true npm start

Ampliar el servidor

1. Crea un nuevo directorio de módulo (p. ej. tasks/)
2. Implementa los manejadores de herramientas en archivos separados
3. Exporta las definiciones de herramientas desde el index.js del módulo
4. Importa y añade herramientas al array TOOLS en el index.js principal
5. Añade pruebas en test/
6. Actualiza docs/quickrefs/tools-reference.md

Documentación

Documentación completa: docs/

Limitaciones conocidas

• Búsqueda en cuentas personales: La query de texto libre y la searchExpression sin formato (antes kqlQuery) dependen de la API $search de Microsoft, que tiene soporte limitado en cuentas personales de Outlook.com — la $search sin formato con ámbito de campo (p. ej. subject:"…") puede no devolver resultados allí. query mitiga esto con una degradación progresiva (filtros OData, luego en el cliente), así que para una búsqueda fiable en cuentas personales prefiere filtros estructurados (from, subject, to, receivedAfter) o query. La búsqueda entre carpetas (searchAllFolders: true) devuelve un superconjunto de los resultados de solo bandeja de entrada.
• Bandeja de entrada centrada: Solo está disponible en cuentas profesionales o educativas de Microsoft 365.
• Buzones compartidos: Requieren el permiso Mail.Read.Shared y una cuenta profesional o educativa.
• Búsqueda de salas de reuniones: Requiere el permiso Place.Read.All con consentimiento del administrador (solo cuentas profesionales o educativas).
• Ruta de exportación predeterminada: Las exportaciones se guardan en el directorio temporal del sistema de forma predeterminada. Usa savePath o outputDir para especificar una ubicación diferente.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para conocer las pautas.

Seguridad

Para problemas de seguridad, consulta nuestra Política de seguridad. No abras problemas públicos para vulnerabilidades.

Historial de cambios

Consulta CHANGELOG.md para ver el historial de versiones.

Acerca de

Creado y mantenido por Little Bear Apps. Outlook Assistant es de código abierto bajo la Licencia MIT.