MailCal

Asistente local de calendario de correo: lee el buzón mediante IMAP, convierte automáticamente en eventos de calendario las entrevistas, evaluaciones, reuniones y fechas límite que aparecen en los correos, ofrece una interfaz de calendario HTML y expone a la vez una API REST y MCP para que herramientas como Codex puedan invocarlas.

Tutorial del blog

Tutorial detallado: Guía de autoayuda para el reclutamiento de otoño: usa MailCal para convertir tu buzón QQ en un calendario de IA y que las entrevistas y evaluaciones entren automáticamente en tu agenda

Configuración del código de autorización de QQ Mail: Tutorial de configuración de IMAP para QQ Mail

Código abierto y contacto

MailCal es de código abierto; agradecemos las estrellas (Star) y los informes de incidencias (Issue).

• Repositorio de GitHub: GlenYe-Coding/MailCal

• Grupo de QQ: 686046608 · Haz clic para unirte al grupo de chat MailCal

Funciones

• Sincronización incremental del buzón: usa un cursor UID para registrar la posición de sincronización y solo procesa los correos nuevos

• Limpieza de correos: convierte HTML en texto plano, elimina scripts y estilos, y conserva los enlaces para su análisis

• Extracción de eventos: motor de reglas + agente LangGraph para determinar si un correo requiere la creación de una tarea pendiente

• Interfaz de calendario: vista mensual / vista semanal, estado de eventos, resumen emergente y renderizado del correo original

• Consola de administración: registros, uso de tokens, estadísticas de correos y limpieza de caché

• Doble interfaz: API REST + MCP, compatible con el servicio local o la integración con Codex

• Compatibilidad de modelos: OpenAI, DeepSeek, Kimi, GLM, Qwen, SiliconFlow, Ollama y servicios personalizados compatibles con OpenAI

Documentación

• Índice de documentación: punto de entrada a toda la documentación de MailCal

• Documentación de API: interfaces REST, parámetros de solicitud, formatos de respuesta y restricciones de errores

• Documentación de MCP: herramientas MCP, restricciones de parámetros y forma de integración con Codex

• Documentación de arquitectura: descripción general del sistema, canalización de sincronización y máquina de estados

• Documentación de configuración: config.json, variables de entorno, caché y configuración de modelos

• Flujo de trabajo de limpieza: proceso estandarizado para convertir correos en eventos

• JSON Schema: formato de salida de correos limpios, eventos y modelos

Estructura del proyecto

MailCal/
├─ src/        后端源码
├─ static/     前端页面、样式、脚本、图片
├─ tests/      单元测试
├─ schemas/    JSON Schema
├─ docs/       全部文档与截图（含文档索引）
├─ scripts/    启动脚本
├─ data/       事件、游标、用量数据
├─ logs/       运行日志
└─ config.json 本地配置

Inicio rápido

cd D:/Project/MailCal
python src/app.py --host 127.0.0.1 --port 5173

Abre http://127.0.0.1:5173 para usar la interfaz de calendario.

En el primer inicio se genera config.json automáticamente; también puedes copiar config.example.json y completar manualmente el código de autorización del buzón y la configuración de los modelos.

En Windows puedes ejecutar directamente scripts/start.bat o scripts/start.ps1.

REST API

Consulta las restricciones completas de parámetros en docs/API.md.

MCP

python src/mcp_server.py

Integración con Codex:

codex mcp add mailcal -- python D:/Project/MailCal/src/mcp_server.py

Modo HTTP:

python src/mcp_server.py --http --port 5174

Dirección de conexión: http://127.0.0.1:5174/mcp

Herramientas disponibles: list_events, get_event, sync_emails, list_models, get_status, reset_sync_cursor, get_usage, reset_usage, add_event, update_event, delete_event.

Consulta las restricciones completas de parámetros en docs/MCP.md.

Configuración

El archivo de configuración es config.json y admite sobrescritura mediante variables de entorno. El código de autorización del buzón y las claves de API de los modelos solo aparecen enmascarados en las respuestas de las interfaces.

Consulta los campos detallados en docs/CONFIGURATION.md y la lista de variables de entorno en .env.example.

Notas de seguridad

• Por defecto solo escucha en 127.0.0.1 y no está abierto a la red pública

• No subas config.json, .env ni las claves de los registros al repositorio de código

• El sid de un correo individual del correo web de QQ caduca con el estado de la sesión; los detalles del evento ofrecen dos accesos fiables: «Abrir QQ Mail» y «Descargar el correo original»

Pruebas

python -m unittest discover -s tests -v