outlook-mcp · MCP de Outlook / Microsoft 365 para Claude

Servidor MCP (Model Context Protocol) que da a un agente (Claude Desktop, Claude Code, Cowork…) control completo sobre el correo de una cuenta de Outlook.com, Hotmail, Live o Microsoft 365 / Office 365: leer, buscar, ver conversaciones, descargar adjuntos, crear carpetas y borradores, mover, archivar, enviar, responder y reenviar.

Usa la API oficial Microsoft Graph con OAuth2 — no IMAP, porque Microsoft desactivó la autenticación básica tanto en Exchange Online como en Outlook.com.

🔒 Sin credenciales en el repositorio. Todo se configura por variables de entorno. La sesión se crea con python authorize.py y se guarda en token.json, que está en .gitignore. Aquí no hay ningún secreto.

---

🧰 Herramientas (18)

Lectura (siempre disponibles)

Tool	Qué hace
outlook_estado	Estado de la cuenta: usuario, candados y carpetas con nº de mensajes/no leídos
outlook_listar_carpetas	Todas las carpetas y subcarpetas, con su id
outlook_listar	Lista los mensajes más recientes de una carpeta (paginado, no marca leído)
outlook_buscar	Busca por remitente, destinatario, asunto, texto, fechas, no leídos, con adjuntos
outlook_buscar_kql	Busca con la sintaxis KQL de Outlook (from:, hasAttachment:true, received>=…, AND/OR/NOT)
outlook_leer	Lee un mensaje completo (cabeceras, cuerpo en texto, adjuntos)
outlook_conversacion	Muestra el hilo entero al que pertenece un mensaje
outlook_descargar_adjunto	Descarga un adjunto (base64 o a disco)

Escritura reversible (siempre disponibles)

Tool	Qué hace
outlook_marcar_leido	Marca leído / no leído
outlook_destacar	Marca para seguimiento (bandera) / quita la marca
outlook_crear_carpeta	Crea una carpeta (o subcarpeta)
outlook_guardar_borrador	Guarda un borrador en Borradores (no envía)

Mover / archivar / eliminados — requieren OUTLOOK_ALLOW_MODIFY=1

Tool	Qué hace
outlook_mover	Mueve un mensaje a otra carpeta
outlook_archivar	Mueve el mensaje a la carpeta Archivo (reversible)
outlook_eliminar	Envía a Elementos eliminados (nunca borra permanente; recuperable)

Envío — requieren OUTLOOK_ALLOW_SEND=1

Tool	Qué hace
outlook_enviar	Envía un correo nuevo (con adjuntos opcionales)
outlook_responder	Responde al remitente o a todos (mantiene el hilo)
outlook_reenviar	Reenvía un mensaje con sus adjuntos

---

🔒 Seguridad

• Candados por variable de entorno, apagados por defecto: enviar (OUTLOOK_ALLOW_SEND) y mover/archivar/eliminar (OUTLOOK_ALLOW_MODIFY). Con ellos apagados, esas tools devuelven un error claro y no hacen nada.
• Leer nunca marca como leído (Graph no altera isRead al leer un mensaje).
• No existe borrado permanente: no hay ninguna tool que haga DELETE en Graph; «eliminar» mueve a Elementos eliminados, recuperable.
• El token (token.json) y el .env están en .gitignore y no se suben.

---

⚙️ Instalación

1) Requisitos

• Python 3.9+
• pip install -r requirements.txt (solo el SDK mcp; el resto es librería estándar)

2) Iniciar sesión (una vez, 1 minuto) — sin registrar nada en Azure

python authorize.py       # muestra un código -> microsoft.com/devicelogin

Por defecto usa el cliente público de Microsoft «Microsoft Graph Command Line Tools», así que no hay que registrar ninguna aplicación: abres el enlace, pegas el código, inicias sesión con tu cuenta de Outlook/Microsoft 365 y ya está. authorize.py guarda token.json y a partir de ahí el servidor refresca el token solo.

<details> <summary>Opcional: usar una aplicación propia de Entra ID</summary>

1. https://entra.microsoft.com → Aplicaciones → Registros de aplicaciones → Nuevo registro.
2. Nombre: outlook-mcp. Tipos de cuenta: «Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft» (o solo personales, según tu caso).
3. Copia el Id. de aplicación (cliente) → OUTLOOK_CLIENT_ID.
4. Autenticación → Configuración avanzada → «Permitir flujos de cliente público» = Sí.
5. (Opcional) Permisos de API → Microsoft Graph → Delegados: Mail.ReadWrite, Mail.Send, User.Read, offline_access. </details>

3) Configuración

cp .env.example .env      # candados y, si quieres, tu propia app o ruta del token

4a) Registrar en Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["C:/ruta/a/outlook-mcp/server.py"],
      "env": {
        "PYTHONUTF8": "1",
        "OUTLOOK_TENANT": "common",
        "OUTLOOK_TOKEN_PATH": "C:/ruta/a/outlook-mcp/token.json",
        "OUTLOOK_ALLOW_SEND": "0",
        "OUTLOOK_ALLOW_MODIFY": "0"
      }
    }
  }
}

Reinicia Claude Desktop después de editarlo.

4b) Instalar en Cowork / Claude Code por URL (como plugin)

Este repo incluye .claude-plugin/marketplace.json:

1. Directorio → Plugins → Añadir marketplace → pega la URL de este repositorio → Sincronizar.
2. Instala el plugin outlook.
3. Configura las variables de entorno en el cliente y ejecuta python authorize.py una vez.

---

🧪 Validación

python test_offline.py    # sin credenciales: no necesita cuenta ni red
python test_gate.py       # contra la cuenta real (solo lectura)

• test_offline.py comprueba, con la red simulada, que cada tool construye la llamada correcta a Graph: que ninguna hace DELETE, que «eliminar» y «archivar» son movimientos de carpeta, el mapeo de nombres de carpeta (papelera → deleteditems…), la construcción de KQL, los destinatarios, el HTML→texto y los adjuntos.
• test_gate.py descubre todas las tools por el protocolo MCP, prueba las de lectura contra la cuenta real, comprueba que los candados bloquean envío y eliminación, y hace el handshake por stdio. No envía nada a terceros ni borra ningún correo.

---

💡 Ejemplos de uso

• «¿Qué me ha llegado hoy sin leer?» → outlook_listar / outlook_buscar
• «Busca los correos del cliente X con adjunto desde junio» → outlook_buscar_kql("from:X hasAttachment:true received>=2026-06-01")
• «Enséñame el hilo completo de esta reclamación» → outlook_conversacion
• «Guárdame el PDF del último correo» → outlook_descargar_adjunto
• «Prepárame un borrador de respuesta» → outlook_guardar_borrador

---

❓ Problemas frecuentes

Síntoma	Causa / solución
No hay sesion de Outlook	Ejecuta python authorize.py una vez
AADSTS7000218 o client_assertion	Falta «Permitir flujos de cliente público» = Sí en Autenticación
AADSTS50194 / cuenta no admitida	El registro no admite cuentas personales: cámbialo a multiinquilino + personales, o usa OUTLOOK_TENANT=consumers
Graph 403 al enviar	Falta el permiso Mail.Send o el candado OUTLOOK_ALLOW_SEND=1
Token caducado tras meses sin uso	Vuelve a ejecutar python authorize.py

---

Genérico y sin datos personales en el código. Configúralo con tu propia cuenta.