outlook-mcp-server

Un servidor MCP local que le da a Claude (Desktop o Code) acceso de lectura/escritura a un buzón personal de Hotmail / Outlook.com a través de la API de Microsoft Graph, usando el flujo de código de autorización OAuth 2.0 (con PKCE) contra la plataforma de identidad de Microsoft.

Expone seis herramientas: list_messages, get_message, search_messages, send_message, create_draft y list_folders.

Todo se ejecuta localmente a través de stdio — no hay ningún servicio alojado, y tu correo nunca pasa por nada más que tu máquina y la propia API de Graph de Microsoft.

Cómo funciona

• Autenticación: MSAL Node ejecuta un flujo de código de autorización + PKCE contra https://login.microsoftonline.com/consumers (solo cuentas personales — consulta Elección de inquilino), usando un servidor HTTP local de corta duración como destino de redirección. Los tokens (incluido el token de actualización offline_access) se almacenan en caché y se renuevan silenciosamente en ejecuciones futuras.

• Almacenamiento: la caché de tokens es serializada por MSAL, cifrada con AES-256-GCM usando una clave generada localmente, y escrita en ~/.outlook-mcp-server/token-cache.enc (modo 0600). La clave en sí reside en ~/.outlook-mcp-server/cache.key (también 0600). Consulta Notas de seguridad para conocer el modelo de amenazas que esto cubre (y no cubre).

• Llamadas a Graph: un cliente delgado basado en fetch llama a https://graph.microsoft.com/v1.0/... con el token de acceso actual.

• Servidor MCP: construido sobre @modelcontextprotocol/sdk, hablando stdio, por lo que puede ser lanzado directamente por Claude Desktop / Claude Code como un proceso hijo.

Related MCP server: Outlook MCP Python

Requisitos previos

• Node.js 18+

• Una cuenta de Microsoft (Hotmail, Outlook.com o Live) — el buzón al que quieres que Claude acceda.

• Una cuenta gratuita de Azure para registrar la aplicación (cualquier cuenta de Microsoft puede hacer esto — no necesita ser una suscripción de Azure de pago).

1. Instalación

git clone <this repo>
cd outlook-mcp-server
npm install

2. Registrar una aplicación en el Portal de Azure

Este registro es lo que emite el ID de cliente que este servidor usa para hablar con Microsoft Graph en tu nombre. npm run setup (abajo) te guía a través de esto interactivamente, pero los pasos son:

1. Ve a portal.azure.com e inicia sesión con cualquier cuenta de Microsoft.

2. Busca Registros de aplicaciones → + Nuevo registro.

3. Completa el formulario:

   • Nombre: cualquier cosa, por ejemplo outlook-mcp-server.

   • Tipos de cuenta admitidos: "Solo cuentas personales de Microsoft". Esto es lo que restringe la aplicación a cuentas de Hotmail/Outlook.com/Live en lugar de un inquilino de trabajo/escuela (Azure AD).

   • URI de redirección: plataforma "Cliente público/nativo (móvil y escritorio)", valor http://localhost:8765/callback (u otro puerto — solo sé consistente cuando el script de configuración lo pida).

4. Haz clic en Registrar, luego copia el ID de aplicación (cliente) de la página de Información general.

5. Ve a Permisos de API → + Agregar un permiso → Microsoft Graph → Permisos delegados, y agrega:

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access (a menudo presente por defecto)

   Los permisos delegados de cuentas personales de Microsoft como estos no necesitan consentimiento de administrador — te das tu propio consentimiento durante el inicio de sesión en el paso 3 a continuación.

6. (Opcional, avanzado) Si prefieres usar un cliente confidencial con un secreto de cliente en lugar del flujo PKCE de cliente público, agrega una URI de redirección de plataforma Web y crea un secreto en Certificados y secretos. La mayoría de las personas deberían omitir esto.

3. Ejecutar la configuración (autenticación + configuración)

npm run setup

Esto hará lo siguiente:

1. Imprimirá el tutorial anterior.

2. Solicitará el ID de cliente (y opcionalmente el secreto / inquilino / URI de redirección), y lo guardará en ~/.outlook-mcp-server/config.json.

3. Abrirá tu navegador para iniciar sesión y dar consentimiento.

4. Verificará que el token funcione llamando a GET /me, imprimiendo tu nombre/correo.

5. Imprimirá el fragmento JSON para agregar a tu configuración de Claude (ver abajo).

Para reautenticarte más tarde (token revocado, cambio de cuenta, etc.) sin volver a ingresar los detalles del registro de la aplicación:

npm run login

4. Compilar y registrar con Claude

npm run build

Claude Desktop — agrega a claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp-server/dist/src/index.js"]
    }
  }
}

Claude Code:

claude mcp add outlook -- node /absolute/path/to/outlook-mcp-server/dist/src/index.js

Reinicia Claude Desktop / Claude Code. Las herramientas a continuación deberían estar disponibles ahora.

Herramientas

Todas las herramientas devuelven JSON (como contenido de texto MCP) y muestran los errores de la API de Graph como errores de herramienta en lugar de bloquear el servidor.

Elección de inquilino

Por defecto, esto usa el inquilino consumers (https://login.microsoftonline.com/consumers), que solo acepta cuentas personales de Microsoft (Hotmail/Outlook.com/Live) — una cuenta de trabajo/escuela será rechazada al iniciar sesión. Si necesitas admitir tanto cuentas personales como cuentas de Azure AD, establece el inquilino en common durante npm run setup (o mediante OUTLOOK_MCP_TENANT=common). Este proyecto está diseñado y probado para el caso de cuentas personales (consumers).

Referencia de configuración

Todo se puede configurar mediante npm run setup (escrito en ~/.outlook-mcp-server/config.json) o mediante variables de entorno, que tienen prioridad — consulta .env.example:

Notas de seguridad

• La caché de tokens está cifrada en reposo con una clave AES-256-GCM generada localmente (~/.outlook-mcp-server/cache.key, modo 0600). Esto protege contra la divulgación casual — commits accidentales, copias de seguridad, otros usuarios sin privilegios en una máquina compartida — pero no contra un atacante que ya tenga acceso de lectura a los archivos de tu cuenta de usuario, ya que la clave se encuentra junto a la caché cifrada. Para una protección más fuerte, reemplaza el ICachePlugin en src/auth/tokenCache.ts por uno respaldado por el llavero de tu sistema operativo (por ejemplo, mediante keytar) — la interfaz del plugin está intencionalmente aislada a ese único archivo.

• Nunca hagas commit de ~/.outlook-mcp-server/ (está fuera del repositorio por defecto) ni de un archivo .env que contenga OUTLOOK_MCP_CLIENT_SECRET.

• send_message envía inmediatamente sin paso de confirmación dentro de este servidor — se espera que Claude confirme la intención contigo antes de llamarlo para cualquier cosa sensible. Prefiere create_draft cuando quieras un paso de revisión.

• Los ámbitos solicitados se limitan a Mail.Read, Mail.ReadWrite, Mail.Send y offline_access — sin calendario, contactos ni acceso más amplio a nivel de aplicación Mail.*.

Solución de problemas

• AADSTS50020 / "la cuenta de usuario ... no existe en el inquilino" — estás accediendo a un inquilino que no acepta cuentas personales, o estás iniciando sesión con una cuenta de trabajo/escuela contra consumers. Confirma que los "Tipos de cuenta admitidos" del registro de la aplicación sean "Solo cuentas personales de Microsoft" y que OUTLOOK_MCP_TENANT sea consumers (o common si intencionalmente quieres ambos).

• AADSTS50011 / discrepancia de URI de redirección — el redirectUri en ~/.outlook-mcp-server/config.json debe coincidir exactamente con una URI de redirección configurada en el registro de la aplicación de Azure, incluido el puerto.

• Errores de herramienta "No has iniciado sesión" — ejecuta npm run login.

• Puerto ya en uso durante la configuración/inicio de sesión — otro proceso está usando el puerto de la URI de redirección; detenlo, o reconfigura el registro de la aplicación y npm run setup con un puerto diferente.

Desarrollo

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

Estructura del proyecto

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup