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)

Escritura reversible (siempre disponibles)

Mover / archivar / eliminados — requieren OUTLOOK_ALLOW_MODIFY=1

Envío — requieren OUTLOOK_ALLOW_SEND=1

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

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.

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

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