personal-mail-mcp

Servidor MCP local para que Codex acceda a cuentas personales de correo y calendario.

Conecta Codex con Microsoft Graph y Gmail para que un asistente local pueda revisar el correo de la bandeja de entrada, buscar confirmaciones de citas, crear o actualizar entradas de calendario, encontrar correos no leídos que puedan haberse pasado por alto fuera de la bandeja de entrada y crear planes de archivo seguros para mensajes de bajo valor. El proyecto también incluye habilidades de Codex para flujos de trabajo recurrentes como la recopilación de citas, el triaje de la bandeja de entrada, la revisión de correos perdidos y la revisión completa del correo.

Este proyecto se proporciona tal cual. Funciona para mi propia configuración, pero no ha sido probado ampliamente en otras cuentas, inquilinos, proveedores de correo o configuraciones de Outlook/Gmail.

Objetivo actual:

• Buzones de correo y calendario de Exchange alojados en GoDaddy a través de Microsoft Graph.

• Gmail a través de las API de Google.

• Herramientas de auditoría/planificación de solo lectura, además de herramientas explícitas de archivo y escritura en calendario.

No se deben confirmar secretos de OAuth ni cachés de tokens. Copia config/accounts.example.toml a config/accounts.toml para la configuración local. Copia config/auth.example.toml a config/auth.toml para la configuración de la aplicación OAuth. Mantén los archivos de configuración locales privados para tu cuenta de usuario.

Permisos recomendados para archivos solo locales:

chmod 700 .private .tokens
chmod 600 config/accounts.toml config/auth.toml config/mail_rules.local.toml

Configuración del proyecto local

Crea e instala el entorno local:

cd <repo-path>
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[providers]'

Configuración de Codex

Añade el servidor MCP a ~/.codex/config.toml:

[mcp_servers.personal_mail]
type = "stdio"
command = "<repo-path>/.venv/bin/python"
args = ["-m", "personal_mail_mcp.server"]
startup_timeout_sec = 30

Reinicia Codex después de cambiar la configuración para que el servidor MCP aparezca en la lista de herramientas activas.

Configuración de la cuenta

Crea config/accounts.toml:

[[accounts]]
id = "exchange_primary"
provider = "microsoft"
email = "primary@example.com"
calendar = true

[[accounts]]
id = "exchange_secondary"
provider = "microsoft"
email = "secondary@example.com"
calendar = false

[[accounts]]
id = "google_primary"
provider = "google"
email = "public-example@gmail.com"
calendar = false

Este archivo es ignorado por git.

Registro de la aplicación de Microsoft

Las cuentas de GoDaddy son cuentas de Exchange Online accesibles a través de Microsoft Graph. No se necesita ninguna API específica de GoDaddy.

1. Abre el centro de administración de Microsoft Entra:

   https://entra.microsoft.com/

2. Ve a:

   Entra ID > App registrations > New registration

   Si la navegación de la izquierda es diferente, busca App registrations en el cuadro de búsqueda del portal.

3. Registra la aplicación:

   Name: personal-mail-mcp
   Supported account types: Single tenant only - your Microsoft 365 tenant

4. En la página de información general del registro de la aplicación, copia:

   Application (client) ID
   Directory (tenant) ID

5. En Autenticación, añade una URL de redirección para una aplicación nativa/local:

   http://localhost

   Esto aparece en Aplicaciones móviles y de escritorio / URLs de redirección en la interfaz actual del portal.

6. En la configuración de Autenticación, habilita los flujos de cliente público/nativo. La redacción del portal puede ser una de estas:

   Allow public client flows
   Enable the following mobile and desktop flows
   Treat application as a public client

   Establécelo en Yes y guarda.

7. En Permisos de API, añade permisos delegados de Microsoft Graph:

   Mail.Read
   Mail.ReadWrite
   Calendars.ReadWrite
   offline_access

Crea config/auth.toml con los IDs copiados:

[microsoft]
client_id = "APPLICATION_CLIENT_ID_FROM_ENTRA"
tenant = "DIRECTORY_TENANT_ID_FROM_ENTRA"

[google]
client_secrets_file = ".private/google-oauth-client.json"

No pongas tokens de OpenAI, ChatGPT, Codex o GitHub en este archivo. Este archivo es ignorado por git.

Conectar cuentas de Exchange Online

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli status
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_primary
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_secondary

Cada comando de conexión imprime una URL de código de dispositivo de Microsoft y un código. Abre la URL, introduce el código e inicia sesión con la cuenta correspondiente:

exchange_primary   -> primary Exchange Online mailbox
exchange_secondary -> secondary Exchange Online mailbox

Las conexiones exitosas escriben archivos de caché de tokens locales en .tokens/, que es ignorado por git.

Verifica:

.venv/bin/python -m personal_mail_mcp.cli status

Las cuentas de Microsoft deberían mostrar:

token_cached: true

Verificación de solo lectura

Obtén los cinco asuntos de mensaje más recientes del buzón principal de Exchange:

.venv/bin/python -m personal_mail_mcp.cli recent-messages exchange_primary --limit 5

La herramienta MCP equivalente expuesta a Codex es:

microsoft_recent_messages(account_id, limit=5)

Configuración de Gmail

Usa un proyecto de Google Cloud para la API de Gmail y las credenciales de escritorio de OAuth.

1. Abre la consola de Google Cloud:

   https://console.cloud.google.com/

2. Crea o selecciona un proyecto, luego habilita:

   Gmail API

3. Configura el consentimiento de OAuth en:

   Google Auth Platform > Branding

   Usa un nombre de aplicación simple como personal-mail-mcp. Para cuentas personales de Gmail, usa la audiencia External y añade tu dirección de Gmail como usuario de prueba en:

   Google Auth Platform > Audience > Test users

4. Crea un cliente de escritorio OAuth en:

   Google Auth Platform > Clients > Create client

   Usa:

   Application type: Desktop app
   Name: personal-mail-mcp

5. Descarga el JSON del cliente OAuth y guárdalo localmente:

   <repo-path>/.private/google-oauth-client.json

   Restringe los permisos:

   chmod 600 .private/google-oauth-client.json

6. Asegúrate de que config/auth.toml apunte al archivo:

   [google]
   client_secrets_file = ".private/google-oauth-client.json"

7. Conecta la cuenta de Gmail:

   cd <repo-path>
   PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect google_primary

   Abre la URL de Google impresa, inicia sesión con el usuario de prueba configurado y aprueba los alcances de lectura/modificación de Gmail.

8. Verifica:

   .venv/bin/python -m personal_mail_mcp.cli status

   La cuenta de Gmail debería mostrar:

   token_cached: true

Obtén los tres asuntos más recientes de la bandeja de entrada de Gmail:

.venv/bin/python -m personal_mail_mcp.cli recent-gmail google_primary --limit 3

La herramienta MCP equivalente expuesta a Codex es:

gmail_recent_messages(account_id, limit=5)

Triaje de correo

El servidor MCP incluye ayudantes reutilizables de auditoría y archivo de la bandeja de entrada para que el triaje repetido no requiera scripts ad hoc.

Ejecuta una auditoría de solo lectura en todas las cuentas:

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli audit-mail exchange_primary exchange_secondary google_primary --limit-per-account 250

Crea un plan de archivo de prueba (dry-run). Esto devuelve solo los candidatos a archivo agrupados en todas las cuentas solicitadas por motivo de archivo, remitente y asunto normalizado. Cada mensaje incluye su ID de cuenta, ID de mensaje, asunto, remitente y fecha de recepción:

.venv/bin/python -m personal_mail_mcp.cli archive-plan exchange_primary exchange_secondary google_primary --limit-per-account 250

Enumera una sola bandeja de entrada con paginación:

.venv/bin/python -m personal_mail_mcp.cli inbox exchange_primary --limit 100

Escanea en busca de correo no leído fuera de la bandeja de entrada, como mensajes archivados o movidos por reglas. El comando clasifica esos mensajes y devuelve los candidatos de atención por separado del archivo/ruido obvio:

.venv/bin/python -m personal_mail_mcp.cli missed-mail exchange_primary exchange_secondary google_primary --limit-per-account 100

Archiva los mensajes seleccionados por ID:

.venv/bin/python -m personal_mail_mcp.cli archive-mail exchange_primary <message-id> [<message-id> ...]

Las herramientas MCP equivalentes expuestas a Codex son:

mail_inbox(account_id, limit=100)
mail_audit(account_ids, limit_per_account=250)
mail_archive_plan(account_ids, limit_per_account=250)
missed_mail(account_ids, limit_per_account=100)
archive_messages(account_id, message_ids)

El clasificador de auditoría es intencionalmente determinista. Agrupa el correo en keep, flag, archive y review. Usa mail_archive_plan como el paso de revisión normal antes de mover los mensajes; es de solo lectura y contiene los IDs exactos necesarios para archive_messages. Cuando el mismo patrón de archivo aparece más de una vez o en varias cuentas, el plan también devuelve recomendaciones de filtro que se pueden usar para crear reglas de buzón/proveedor para futuros mensajes.

La creación remota de filtros/reglas es posible, pero requiere alcances de OAuth adicionales: las reglas de mensaje de Microsoft Graph requieren MailboxSettings.ReadWrite; la creación de filtros de Gmail requiere gmail.settings.basic. Hasta que se añadan y aprueben, el servidor solo debería recomendar filtros en lugar de crearlos.

Los valores predeterminados reutilizables residen en config/mail_rules.default.toml. Los remitentes específicos del usuario, los recuentos de retención y los patrones de archivo pertenecen a config/mail_rules.local.toml, que es ignorado por git. Usa config/mail_rules.example.toml como plantilla para las anulaciones locales.

Habilidad opcional de Codex

Este proyecto incluye una habilidad de Codex compartible:

skills/email-appointment-harvest
skills/inbox-triage
skills/missed-mail-review
skills/review-all-mail

La habilidad documenta el flujo de trabajo repetible para escanear correos electrónicos recientes, proponer candidatos para citas/calendario, esperar la aprobación y luego crear o actualizar solo las entradas de calendario aprobadas.

Instálala en un entorno de Codex:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/email-appointment-harvest "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/inbox-triage "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/missed-mail-review "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/review-all-mail "${CODEX_HOME:-$HOME/.codex}/skills/"

Reinicia Codex después de la instalación. Solicitud de ejemplo:

Use email appointment harvest to scan the last 7 days of email for appointments,
propose calendar entries, and add only the entries I approve.

La habilidad instalada asume que este servidor MCP está configurado en Codex y que los tokens de OAuth de correo/calendario ya se han conectado.

Notas de seguridad

• config/auth.toml, config/accounts.toml y .tokens/ son solo locales.

• La aplicación de Microsoft es un cliente público/nativo; no crees ni almacenes un secreto de cliente para este flujo de CLI.

• Las credenciales de cliente de Gmail en .private/ y las cachés de tokens en .tokens/ deben tener el modo 600 para archivos y 700 para directorios.

• Se requieren Mail.ReadWrite de Microsoft, gmail.modify de Google y Calendars.ReadWrite de Microsoft para las herramientas actuales de archivo/calendario. Mantén el registro de la aplicación limitado solo a los permisos delegados que utilices.

• Trata archive_messages y las herramientas de mutación de calendario como acciones de escritura. Prefiere mail_archive_plan y las lecturas de calendario antes de aplicar cambios.

• Rota cualquier token de acceso personal que se haya almacenado alguna vez en una configuración de texto plano.