把邮箱变成 AI 智能日历：MailCal 从 GitHub 下载到配置使用全流程

MailCal从 GitHub 下载到配置使用的完整教程MailCal 是一个本地邮件日历管家通过IMAP读取 QQ 邮箱自动把邮件里的面试、测评、会议和截止日期整理成日历事件并提供REST API和MCP接口。1. 从 GitHub 下载项目项目地址https://github.com/GlenYe-Coding/MailCal方式一Git Clonegitclone https://github.com/GlenYe-Coding/MailCal.gitcdMailCal方式二下载 ZIP打开 GitHub 仓库主页点击页面上的Code按钮选择Download ZIP解压到本地目录2. 环境准备需要Python 3.10 或更高版本。进入项目目录后安装依赖cdMailCal pipinstall-rrequirements.txt3. 获取 QQ 邮箱授权码MailCal 使用IMAP同步 QQ 邮箱需要先在网页版开启 IMAP/SMTP 服务并生成授权码。详细步骤可以参考已经发布的教程QQ 邮箱 IMAP 配置教程4. 配置文件项目默认使用config.json保存配置。首次启动会自动生成空模板也可以手动复制示例配置copy config.example.json config.json编辑config.json{email_provider:qq,email:nameqq.com,auth_code:your-qq-auth-code,imap_host:imap.qq.com,imap_port:993}auth_code填写的是 QQ 邮箱授权码不是登录密码。如果使用模型提取事件还需要在model节点填写厂家、API Base 和API Key{model:{enabled:true,provider:deepseek,api_base:https://api.deepseek.com/v1,api_key:your-api-key,model_name:deepseek-chat}}5. 启动项目启动 Web 界面python src/app.py--host127.0.0.1--port5173浏览器打开http://127.0.0.1:5173启动 MCP 服务python src/mcp_server.py--http--port5174MCP 地址http://127.0.0.1:5174/mcpCodex 接入命令codex mcpaddmailcal -- python D:/Project/MailCal/src/mcp_server.py6. 使用教程6.1 配置邮箱和模型点击右上角“设置”在“邮箱”区域填写 QQ 邮箱、授权码和 IMAP 服务器在“模型配置”区域填写模型厂家、API Base 和 API Key。6.2 同步邮件点击顶部“同步邮件”按钮MailCal 会通过 IMAP增量拉取邮件并自动把可行动的邮件清洗成日历事件。左侧“同步状态”会显示上次同步时间同步游标 UID已同步邮件数量6.3 查看日历事件在月视图或周视图中鼠标悬停事件可快速查看摘要包括时间、状态和邮件链接数量点击事件可展开完整详情查看邮件原文和邮件链接事件支持手动标记完成或取消事件根据开始和结束时间自动进入待开始、进行中、已逾期等状态点击事件后弹窗会展开事件详情包括时间、类型、状态、来源邮件、发件人、说明、邮件链接和邮件原文。6.4 手动添加事件点击顶部“添加事件”可以手动创建会议、面试、测评或截止事件。填写标题、开始时间、结束时间、类型和备注后点击“保存”即可写入日历。6.5 后台控制台点击顶部“后台”可以查看运行日志Token 用量与费用邮件统计缓存清理运行日志使用表格展示时间、级别、模块和内容方便排查同步问题。7. REST API 与 MCPREST API 和 MCP 共用同一套事件校验规则接口文档位于docs/API.md和docs/MCP.md。常用接口curlhttp://127.0.0.1:5173/api/healthcurlhttp://127.0.0.1:5173/api/eventscurl-XPOST http://127.0.0.1:5173/api/sync如何用 codex 等通过本地 mcp 操控8. 安全提醒config.json不要提交到 GitHub授权码、邮箱地址和模型 API Key 都属于敏感信息默认服务只监听127.0.0.1不要直接暴露到公网发布截图前先检查是否露出个人信息