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