useful-outlook-mcp

Un servidor MCP remoto para Microsoft Outlook con OAuth2 adecuado y herramientas optimizadas para agentes.

Características

• Conforme a la especificación: metadatos OAuth RFC 9728/8414, registro dinámico de clientes RFC 7591

• OAuth sin estado: tokens gestionados por el cliente, no por el servidor, tal como OAuth pretendía

• Herramientas optimizadas para agentes: ingeniería de prompts exhaustiva en las descripciones de las herramientas

• Ámbitos dinámicos: los ámbitos OAuth se ajustan automáticamente a las herramientas habilitadas

• Listo para producción: Docker, limitación de tasa, modo de solo lectura, filtrado de herramientas

Related MCP server: M365 MCP Server

Inicio rápido

npm install
npm run build
npm start  # Server at http://localhost:3000

Entorno requerido:

MS365_MCP_CLIENT_ID=your-azure-ad-client-id
MS365_MCP_CLIENT_SECRET=your-azure-ad-client-secret
MS365_MCP_TENANT_ID=your-tenant-id  # or 'common'

Configuración de Azure AD

1. Azure Portal → Microsoft Entra ID → Registros de aplicaciones → Nuevo

2. Añade permisos delegados: User.Read, Mail.Read, Mail.ReadWrite, Mail.Send, Calendars.Read, Calendars.ReadWrite, Calendars.Read.Shared, Place.Read.All, People.Read, offline_access

3. Añade el URI de redirección: http://localhost:6274/oauth/callback (para MCP Inspector)

4. Certificados y secretos → Nuevo secreto de cliente → Copia el valor

5. Copia el ID de cliente, el secreto de cliente y el ID de inquilino en tu .env

Herramientas

Correo

list-mail-folders · list-mail-messages · search-mail · get-mail-message · send-mail · create-draft-mail · reply-mail · reply-all-mail · create-reply-draft · create-reply-all-draft · delete-mail-message · move-mail-message

Calendario

list-calendars · list-calendar-events · search-calendar-events · find-meeting-times · get-calendar-event · get-calendar-view · create-calendar-event · update-calendar-event · delete-calendar-event

Personas

lookup-contact-email

Búsqueda de salas

Para reuniones presenciales, find-meeting-times automáticamente:

• Obtiene todas las salas de reuniones disponibles en tu organización

• Las incluye en las comprobaciones de disponibilidad junto con los asistentes

• Agrupa las salas libres por ubicación (ciudad/edificio)

• Devuelve solo las salas disponibles con direcciones de correo para reservarlas

Establece isOnlineMeeting: false para habilitar la búsqueda de salas. Para reuniones en línea (por defecto: true), los enlaces de reuniones de Teams se generan automáticamente.

Ámbito requerido: Place.Read.All (añádelo a los permisos de la aplicación de Azure AD)

Configuración

Docker

Desde GitHub Container Registry:

docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  ghcr.io/Leonine-Studios/useful-outlook-mcp:latest

O constrúyelo localmente:

docker build -t useful-outlook-mcp .
docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  useful-outlook-mcp

Endpoints

Pruebas

npm run dev
npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp

Notas de diseño

Problemas con los servidores existentes

1. Arquitectura heredada: construido como stdio con HTTP acoplado. Este es nativo de HTTP.

2. OAuth mal implementado: la mayoría de los servidores almacenan los tokens en el lado del servidor. Este servidor no tiene estado: los tokens se pasan en cada solicitud mediante la cabecera Authorization y nunca se almacenan.

3. Herramientas sin reflexión: los servidores típicos mapean los endpoints de la API 1:1 sin orientación. Los agentes fallan en el uso práctico porque no conocen las peculiaridades de la API ni los flujos de trabajo de varios pasos.

Qué es diferente

Cada herramienta incluye:

• Cuándo usarla frente a las alternativas

• Peculiaridades conocidas de Graph API (hay muchas)

• Orientación sobre flujos de trabajo para tareas de varios pasos

• Combinaciones de parámetros que fallan

Ejemplo: find-meeting-times explica que las direcciones de correo son obligatorias (los nombres no funcionan), cómo encontrar los correos a partir de los nombres usando search-mail, qué significa OrganizerUnavailable y que isOrganizerOptional=true requiere confirmación del usuario.

Peculiaridades conocidas de Graph API

• Filtrado de correo por remitente: eq en from/emailAddress/address no es fiable: usa startswith()

• Filtrado de correo por destinatario: no se pueden filtrar para/cc/bcc con $filter; hay que usar $search

• Filtrado del calendario por organizador: $filter en el correo del organizador devuelve 500; se filtra en el lado del cliente

• Concurrencia: las llamadas paralelas pueden devolver errores MailboxConcurrency

• Búsqueda + ordenación: $search no se puede combinar con $orderby

Licencia

MIT