MailCal

本地邮件日历管家：通过 IMAP 读取邮箱，把邮件中的面试、测评、会议、截止日期自动清洗成日历事件，提供 HTML 日历界面，并同时暴露 REST API 和 MCP，供 Codex 等工具调用。

博客教程

详细教程：秋招自救指南：用 MailCal 把 QQ 邮箱变成 AI 日历，面试测评自动进日程

QQ 邮箱授权码配置：QQ 邮箱 IMAP 配置教程

开源与联系

MailCal 已开源，欢迎 Star 和 Issue 反馈。

• GitHub 仓库：GlenYe-Coding/MailCal
• QQ 群：686046608 · 点击加入群聊 MailCal

功能

• 增量同步邮箱：使用 UID 游标记录同步位置，只处理新增邮件
• 邮件清洗：HTML 转纯文本、删除脚本样式、保留链接供分析
• 事件提取：规则引擎 + LangGraph Agent 判断邮件是否需要创建待办
• 日历界面：月视图 / 周视图、事件状态、悬浮摘要、邮件原文渲染
• 后台控制台：日志、Token 用量、邮件统计、缓存清理
• 双接口：REST API + MCP，支持本地服务或 Codex 接入
• 模型适配：OpenAI、DeepSeek、Kimi、GLM、Qwen、SiliconFlow、Ollama、自定义 OpenAI 兼容服务

文档

• 文档索引：MailCal 全部文档入口
• API 文档：REST 接口、请求参数、响应格式、错误约束
• MCP 文档：MCP 工具、参数约束、Codex 接入方式
• 架构文档：系统总览、同步流水线、状态机
• 配置文档：config.json、环境变量、缓存和模型配置
• 清洗工作流：邮件到事件的标准化处理流程
• JSON Schema：清洗邮件、事件、模型输出格式

项目结构

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

快速启动

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

打开 http://127.0.0.1:5173 使用日历界面。

首次启动会自动生成 config.json；也可以复制 config.example.json 手动填写邮箱授权码和模型配置。

Windows 可直接运行 scripts/start.bat 或 scripts/start.ps1。

REST API

方法	路径	说明
GET	/api/health	健康检查
GET	/api/state	配置、事件、同步状态和用量
GET	/api/events	事件列表
GET	/api/events/{id}	单个事件
POST	/api/events	添加事件
PUT / PATCH	/api/events	修改事件
DELETE	/api/events	删除事件
POST	/api/sync	立即同步邮箱
GET / POST	/api/models	获取可用模型列表
POST	/api/config	保存配置
GET	/api/usage	Token 用量与费用
DELETE	/api/usage	清零用量
DELETE	/api/sync-cursor	重置同步游标
GET	/api/admin/stats	后台统计
GET	/api/admin/logs	运行日志
POST	/api/admin/clear	清理缓存 / 日志 / 用量 / 事件
GET	/api/emails/{uid}/raw	下载原始邮件 .eml
GET	/api/export.ics	导出 ICS 日历
GET	/api/openapi.json	OpenAPI 摘要

完整参数约束见 docs/API.md。

MCP

python src/mcp_server.py

Codex 接入：

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

HTTP 模式：

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

连接地址：http://127.0.0.1:5174/mcp

可用工具：list_events、get_event、sync_emails、list_models、get_status、reset_sync_cursor、get_usage、reset_usage、add_event、update_event、delete_event。

完整参数约束见 docs/MCP.md。

配置

配置文件为 config.json，支持环境变量覆盖。邮箱授权码和模型 API Key 只会以掩码形式出现在接口响应中。

详细字段见 docs/CONFIGURATION.md，环境变量清单见 .env.example。

安全说明

• 默认只监听 127.0.0.1，不对公网开放
• 请勿把 config.json、.env、日志中的密钥提交到代码仓库
• QQ 网页邮箱的单封邮件 sid 会随登录态失效；事件详情提供“打开 QQ 邮箱”和“下载原始邮件”两个可靠入口

测试

python -m unittest discover -s tests -v