email-mcp

Correo electrónico y calendario mediante Outlook clásico en Windows, controlado a través de COM nativo (pywin32). Se distribuye como un único comando email que es a la vez una CLI y un servidor MCP stdio. Sin registro de aplicación en Azure, sin OAuth, sin PowerShell: simplemente controla el cliente de escritorio de Outlook en el que ya has iniciado sesión.

Requisitos

• Windows 10/11

• Outlook clásico de escritorio, configurado con al menos una cuenta

• Python 3.10+ y uv

El Outlook "nuevo" para Windows no expone COM. Si usas el nuevo Outlook y no puedes volver al clásico, esto no funcionará para ti.

Solo se accede a COM a través del cliente de escritorio de Outlook; no hay autenticación separada. La cuenta que haya iniciado sesión en Outlook es la que ve la herramienta, y el correo enviado llega a la carpeta Elementos enviados real exactamente como si lo hubieras enviado a mano.

Related MCP server: outlook-mcp

Instalar / Ejecutar

Ejecútalo directamente desde GitHub con uvx (sin clonar ni instalar manualmente):

uvx --from git+https://github.com/kerodkibatu/email-mcp email --help

uv resuelve y guarda en caché el paquete en la primera ejecución; las invocaciones posteriores son rápidas.

CLI

Cada herramienta es un subcomando de email. La salida es JSON en stdout.

# List configured Outlook accounts
uvx --from git+https://github.com/kerodkibatu/email-mcp email list-accounts

# Query across all mail folders with a MongoDB-style filter (JSON string)
uvx --from git+https://github.com/kerodkibatu/email-mcp email query \
  --filter '{"$and":[{"from":{"$contains":"@kyros.com"}},{"unread":true}]}' \
  --limit 20 --order-by received_desc

# Read one email by EntryID
uvx --from git+https://github.com/kerodkibatu/email-mcp email read --entry-id "0000000..."

# Send a new mail (account is REQUIRED — see below)
uvx --from git+https://github.com/kerodkibatu/email-mcp email send \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

# Save a new mail as a draft instead of sending (same flags as send, no --send-as)
uvx --from git+https://github.com/kerodkibatu/email-mcp email draft \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

MCP

email mcp arranca un servidor MCP stdio que expone las 11 herramientas. Añádelo a tu .mcp.json (o claude_desktop_config.json):

{
  "mcpServers": {
    "email": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kerodkibatu/email-mcp", "email", "mcp"]
    }
  }
}

El primer arranque es más lento mientras uv resuelve el paquete; los arranques posteriores usan la caché.

Herramientas

Elegir la cuenta de envío

send_email, reply_email y forward_email requieren un parámetro account: una subcadena del nombre de la cuenta de Outlook configurada (normalmente la dirección SMTP). Esto es intencionado: con varias cuentas configuradas (p. ej., personal + trabajo), usar por defecto la cuenta principal de Outlook es un tiro en el pie: así es como el correo personal se filtra desde una cuenta de trabajo o viceversa. Obligar a quien llama a indicar la cuenta hace que el envío sea explícito.

Si el account proporcionado no coincide con ninguna cuenta configurada (subcadena que no distingue mayúsculas/minúsculas), la herramienta devuelve un error y enumera las cuentas disponibles. Ejecuta list_accounts primero si aún no conoces el nombre. La cuenta de transporte se establece directamente en el elemento de Outlook mediante SendUsingAccount.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "kerod@towlydigital.com"
}

Enviar como (EXPERIMENTAL — se requiere el permiso "Enviar como" de Exchange)

EXPERIMENTAL. Esto controla Outlook clásico únicamente a través de pywin32 COM; no existe una vía Azure/OAuth. El comportamiento depende de la política del inquilino y puede rebotar, degradarse silenciosamente o dejar el mensaje en la Bandeja de salida. Trátalo como una operación de mejor esfuerzo.

send_email, reply_email y forward_email aceptan un parámetro opcional send_as: una dirección SMTP desde la que enviar. El destinatario ve esa dirección como remitente, sin indicación de "en nombre de". Esto es el verdadero Enviar como de Exchange, distinto de Enviar en nombre de.

Mecánicamente, la herramienta establece SendUsingAccount en la account que proporcionas (el buzón de transporte) y, a continuación, resuelve send_as contra Exchange y sobrescribe tanto las propiedades MAPI PR_SENT_REPRESENTING_* como PR_SENDER_* (mediante el PropertyAccessor del elemento) para que apunten a esa dirección antes de enviarlo. Sobrescribir las propiedades del remitente (no solo las de representación) es lo que convierte el "en nombre de" en un Enviar como puro. Exchange valida el permiso en el momento del envío.

Requisitos:

• El usuario de account debe tener permiso de Enviar como en el buzón de send_as, concedido en el servidor por un administrador de Exchange. La herramienta no puede conceder ni comprobar este permiso; solo puede intentar el envío.

• La dirección send_as debe ser resoluble por Exchange; normalmente se trata de un buzón del mismo inquilino. Las direcciones externas (gmail.com, etc.) fallarán al resolverla con un error.

• Si falta el permiso, el comportamiento depende de la política del inquilino: Exchange puede rebotar el mensaje, degradarlo silenciosamente a "en nombre de" o dejarlo en la Bandeja de salida.

• Esta función solo funciona dentro de una organización de Exchange que la haya autorizado explícitamente. No se puede usar para suplantar a remitentes externos.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "admin@custom.com",
  "send_as": "contact@custom.com"
}

La respuesta incluye un campo sent_as que refleja la dirección cuando se usó send_as.

Envío de archivos adjuntos

send_email acepta un array opcional attachments de rutas de archivo absolutas. Cada ruta debe existir y apuntar a un archivo normal; si alguna ruta no es válida, la herramienta devuelve un error que enumera las infractoras y no envía. En Windows se aceptan tanto la barra diagonal como la barra invertida; ~ y las variables de entorno no se expanden: pasa rutas completamente resueltas.

{
  "to": "kerod@example.com",
  "subject": "Signed contract",
  "body": "See attached.",
  "account": "kerod@towlydigital.com",
  "attachments": [
    "C:\\Users\\Kerod\\Desktop\\contract.pdf",
    "C:/Users/Kerod/Desktop/cover-letter.pdf"
  ]
}

Descarga de archivos adjuntos

La herramienta download_attachments extrae los archivos de un correo y los guarda localmente, devolviendo la ruta absoluta de la carpeta.

• Ubicación: Los archivos se guardan en la carpeta de Descargas del usuario: ~/Downloads/email-attachments/YYYY-MM-DD_<sender>_<subject>/.

• Imágenes incrustadas: Los logotipos y las imágenes de firma se filtran de forma predeterminada para evitar el desorden. Establece include_inline: true si los necesitas específicamente.

• Idempotencia: Volver a ejecutar la herramienta sobre el mismo correo reutiliza la carpeta de forma segura (controlado mediante un marcador .entry_id) y desambigua cuando dos correos distintos generan el mismo slug.

Cómo funciona

El comando email se conecta a una instancia de Outlook en ejecución mediante COM (recurriendo a iniciar una si no hay ninguna en ejecución) y, a continuación, controla el espacio de nombres MAPI para leer y escribir correo. Todo el acceso a COM pasa por una única sesión de Outlook; la herramienta nunca inicia PowerShell.

Esto significa:

• Outlook debe estar instalado (no es necesario que esté abierto: la primera llamada lo iniciará)

• La cuenta que haya iniciado sesión en Outlook es la que ve la herramienta: sin autenticación separada

• El correo enviado aparece en la carpeta Elementos enviados del usuario exactamente como si lo hubiera enviado manualmente

Licencia

MIT — consulta LICENSE.