Outlook Assistant

Outlook Assistant

Servidor MCP para correo electrónico, 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 Protocolo de Contexto de Modelo. Pídele a tu asistente de IA que busque en tu bandeja de entrada, envíe correos electrónicos, 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 de entrada → leer y resumir → redactar una respuesta, todo desde la conversación}

Lo que puedes hacer

• 📨 Buscar y leer correos electrónicos — encuentra mensajes por remitente, asunto, fecha o palabras clave; lee hilos completos con agrupación de conversaciones; marca, mueve, exporta o categoriza varios correos a la vez
• 🛡️ Enviar correos con controles de seguridad — vista previa de prueba, avisos de correo antes del envío (fuera de oficina, buzón lleno, restricciones de entrega), límite de velocidad 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; previsualiza antes de guardar con el modo de prueba
• 📅 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 de conversación completos a MBOX o HTML; exporta en lote 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 investigar phishing y revisar cumplimiento
• 🗂️ Organizar tu bandeja de entrada — crea carpetas anidadas (direccionables por ruta), configura reglas de bandeja de entrada, codifica con colores mediante categorías, gestiona la Bandeja de entrada prioritarios: todo funciona en conjunto para una automatización completa
• 🔄 Seguimiento de cambios en la bandeja de entrada — la sincronización delta 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 organizativo, 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 entrada de equipos y cuentas de servicio (Microsoft 365)
• 🏢 Buscar salas de reuniones — busca por edificio, planta, capacidad, equipo audiovisual y accesibilidad para sillas de ruedas (Microsoft 365)

¿Por qué Outlook Assistant?

Características

22 herramientas en total — consolidadas a partir de 55 para un rendimiento óptimo de la IA. Consulta la Referencia de herramientas para ver los parámetros completos.

Formatos de exportación

La compatibilidad de formatos varía según target:

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

Compatibilidad de cuentas

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

Nota: En cuentas personales, la API $search de Microsoft tiene compatibilidad limitada para consultas de texto libre. Outlook Assistant gestiona esto 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 estructurados (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, e informa cuál respondió en _meta.searchMetadata junto con cualquier filtro que no pudo aplicar (droppedFilters). La mayoría de los envoltorios de Graph API fallan silenciosamente; este se adapta y te lo dice.
• Informática 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 analizan en la conversación).
• Sincronización delta — el monitoreo incremental de la bandeja de entrada devuelve solo lo que cambió 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 en lote — marca, mueve, exporta o categoriza varios correos en una sola llamada. La exportación basada en búsqueda te permite exportar resultados en lote sin recopilar IDs manualmente.
• Inteligencia previa al envío — comprueba destinatarios por 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 la bandeja de entrada 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 ante todo para el acceso a correo mediante IA:

Protecciones para acciones destructivas — Cada herramienta lleva anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint) para que los clientes de IA puedan aprobar automáticamente lecturas seguras y solicitar confirmación para operaciones destructivas como enviar correos o eliminar eventos.

Protecciones para el envío de correos — La herramienta send-email incluye:

• Avisos de correo antes del envío (checkRecipients: true) — comprueba destinatarios por fuera de oficina, buzón lleno y restricciones de entrega antes de enviar
• Modo de prueba (dryRun: true) — previsualiza correos redactados sin enviarlos
• Límite de velocidad por sesión — configurable mediante OUTLOOK_MAX_EMAILS_PER_SESSION (predeterminado: 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 su estado e imprime una sugerencia de configuración cuando no están establecidos. Consulta .mcp.json.example para ver una plantilla de 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 de prueba, lista de destinatarios permitidos, validación de avisos de correo y límite de velocidad. La acción send comparte el contador de límite de velocidad de send-email, evitando la evasión mediante la ruta de redactar y luego enviar.

Arquitectura optimizada en tokens — Las herramientas se consolidan mediante el enfoque STRAP (Herramienta Única, Recurso, Patrón de Acción). 22 herramientas en lugar de 55 reduce la sobrecarga por turno en ~11 000 tokens (~64 %), manteniendo más del contexto de la IA disponible para tu conversación real. Menos herramientas también significa que la 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 protecciones son medidas de defensa en profundidad que reducen el riesgo, pero no son una garantía contra acciones no intencionadas. El acceso a tu correo mediante IA es inherentemente sensible: revisa siempre las llamadas a herramientas antes de aprobarlas, especialmente en envíos y eliminaciones. Ninguna protección 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 ejecuta directamente sin instalar:

npx @littlebearapps/outlook-assistant

Para comprobar qué versión tienes o ver las opciones disponibles:

outlook-assistant --version     # prints e.g. 3.11.1
outlook-assistant --help        # usage, options and key environment variables

Sin argumentos, el servidor habla el Protocolo de Contexto de Modelo a través de stdio. Normalmente lo lanza tu cliente MCP en lugar de ejecutarlo manualmente: si se inicia desde una terminal, simplemente esperará en stdin.

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 tutorial 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. Agrega 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 clientes públicos" en Autenticación > Configuración avanzada
6. (Opcional) Establece la URI de redirección a http://localhost:3333/auth/callback — solo se necesita para el flujo de autenticación del navegador

3. Configura tu Cliente MCP

Agrega 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. Autenticación

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 los 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 ejecutas el servidor de autenticación por separado, asegúrate de que estas estén establecidas 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 la 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

Opciones de CLI

Un argumento no reconocido se informa en stderr y sale con código 1, en lugar de iniciar un servidor que lo ignoraría.

Registro de aplicación de Azure

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

Crear la aplicación

1. Abre Azure Portal
2. Inicia sesión con una cuenta de Microsoft de trabajo o personal
3. Busca Registros de aplicaciones y haz clic en Nuevo registro
4. Ingresa un nombre (por ejemplo, "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)

Agregar permisos

1. Ve a Permisos de API > Agregar un permiso > Microsoft Graph > Permisos delegados
2. Agrega estos permisos requeridos:
   • offline_access — tokens de actualización entre sesiones
   • User.Read — perfil básico
   • Mail.Read, Mail.ReadWrite, Mail.Send — operaciones de correo electrónico
   • 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, agrega permisos solo de organización (solo cuentas de trabajo o escuela):
   • 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. Ingresa una descripción y selecciona la expiración
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 para compatibilidad con versiones anteriores.

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

Configuración del cliente MCP

Consulta Inicio rápido — Configura tu cliente MCP 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 todas partes, incluidos entornos 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) en cualquier navegador, cualquier dispositivo
3. Ingresa el código, inicia sesión con tu cuenta de Microsoft y concede los permisos
4. Dile 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 clientes 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 persiste 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 (por ejemplo, puente Untether/Telegram, cambios de sesión de Claude Desktop).

Flujo de redirección del navegador (alternativa)

Para desarrollo en localhost o si prefieres el flujo OAuth tradicional:

npm run auth-server

Esto inicia un servidor local en el puerto 3333 para manejar 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 los 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 en OUTLOOK_CLIENT_SECRET.

El Valor se muestra solo una vez, cuando se crea el secreto — si has navegado fuera, no se puede leer de nuevo, así que crea un nuevo secreto. Un secreto expirado produce este mismo error, así que revisa también la columna Expira.

Desde la v3.11.0, el servidor detecta este error y agrega la explicación al mensaje original de Microsoft, para que veas tanto el código de error sin procesar como qué hacer al respecto.

La URL de autenticación no funciona

Si usas el flujo del 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 clientes públicos" en Azure Portal > Registros de aplicaciones > Autenticación > Configuración avanzada.

La actualización del token falla después de ~60 minutos (autenticación con código de dispositivo)

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

Respuestas de API vacías

Verifica el estado de autenticación con la herramienta auth (action=status). Los tokens pueden haber expirado — 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

Extender el servidor

1. Crea un nuevo directorio de módulo (por ejemplo, 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 agrega herramientas al arreglo TOOLS en el index.js principal
5. Agrega pruebas en test/
6. Actualiza docs/quickrefs/tools-reference.md

Documentación

Documentación completa: docs/

Limitaciones conocidas

• Búsqueda en cuentas personales: La búsqueda de texto libre query y la searchExpression sin procesar (anteriormente kqlQuery) dependen de la API $search de Microsoft, que tiene soporte limitado en cuentas personales de Outlook.com. query mitiga esto con un respaldo progresivo (filtros OData, filtros booleanos y luego un escaneo del lado del cliente). La búsqueda $search con ámbito de campo (por ejemplo, subject:"…") se rechaza directamente allí; desde v3.10.0, las expresiones from:/to:/subject: se traducen a los filtros OData equivalentes más cercanos y se reintentan, pero los operadores booleanos, la agrupación, los comodines y otros prefijos de campo no se traducen; esos aún terminan con un resultado explícito de sin resultados en lugar de una búsqueda más amplia silenciosa. Los filtros estructurados (from, subject, to, receivedAfter) siguen siendo la ruta más directa. La búsqueda entre carpetas (searchAllFolders: true) devuelve un superconjunto de los resultados de solo la bandeja de entrada. Ten en cuenta que query y searchExpression no son intercambiables allí: searchExpression va a $search, que coincide con todo el mensaje, incluido el cuerpo, y clasifica por relevancia en lugar de por fecha, mientras que query recurre a una coincidencia de subcadena en el asunto que nunca lee los cuerpos.
• Profundidad de búsqueda to en cuentas personales: el filtro de destinatario del lado del servidor se rechaza, por lo que to se compara localmente sobre los 500 mensajes más recientes (OUTLOOK_SEARCH_SCAN_LIMIT, máximo 5000). En un archivo grande que excluye correos más antiguos, combina to con receivedAfter/receivedBefore. Desde v3.11.1, la respuesta lo indica siempre que el escaneo se haya truncado, haya coincidido o no.
• Bandeja de entrada destacada: Solo disponible en cuentas de trabajo o escuela de Microsoft 365.
• Buzones compartidos: Requieren permiso Mail.Read.Shared y una cuenta de trabajo o escuela.
• Búsqueda de salas de reuniones: Requiere permiso Place.Read.All con consentimiento de administrador (solo cuentas de trabajo o escuela).
• 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 obtener las pautas.

Seguridad

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

Registro 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.