MailCal

Local email calendar manager: reads emails via IMAP, automatically extracts interviews, assessments, meetings, and deadlines from emails into calendar events, provides an HTML calendar interface, and exposes both REST API and MCP for tools like Codex.

Blog Tutorial

Detailed tutorial: Job Hunting Guide: Use MailCal to Turn QQ Mail into an AI Calendar, Interviews and Assessments Automatically Added to Schedule

QQ Mail authorization code configuration: QQ Mail IMAP Configuration Tutorial

Open Source & Contact

MailCal is open source. Welcome to star and submit issues.

• GitHub Repository: GlenYe-Coding/MailCal

• QQ Group: 686046608 · Click to join MailCal QQ Group

Features

• Incremental email sync: uses UID cursor to track sync position, only processes new emails

• Email cleaning: converts HTML to plain text, removes scripts and styles, preserves links for analysis

• Event extraction: rule engine + LangGraph Agent to determine whether an email should create a todo

• Calendar interface: month view / week view, event status, hover summary, original email rendering

• Admin console: logs, Token usage, email statistics, cache clearing

• Dual interfaces: REST API + MCP, supports local service or Codex integration

• Model support: OpenAI, DeepSeek, Kimi, GLM, Qwen, SiliconFlow, Ollama, custom OpenAI-compatible services

Documentation

• Documentation Index: entry point for all MailCal documentation

• API Documentation: REST endpoints, request parameters, response formats, error constraints

• MCP Documentation: MCP tools, parameter constraints, Codex integration guide

• Architecture Documentation: system overview, sync pipeline, state machine

• Configuration Documentation: config.json, environment variables, cache and model configuration

• Cleaning Workflow: standardized email-to-event processing pipeline

• JSON Schema: output formats for cleaned emails, events, and models

Project Structure

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

Quick Start

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

Open http://127.0.0.1:5173 to use the calendar interface.

On first launch, config.json will be generated automatically; you can also copy config.example.json and manually fill in the email authorization code and model configuration.

On Windows, you can directly run scripts/start.bat or scripts/start.ps1.

REST API

For full parameter constraints, see docs/API.md.

MCP

python src/mcp_server.py

Codex integration:

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

HTTP mode:

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

Connection address: http://127.0.0.1:5174/mcp

Available tools: list_events, get_event, sync_emails, list_models, get_status, reset_sync_cursor, get_usage, reset_usage, add_event, update_event, delete_event.

For full parameter constraints, see docs/MCP.md.

Configuration

The configuration file is config.json, which supports environment variable overrides. Email authorization codes and model API keys will only appear in API responses in masked form.

For detailed fields, see docs/CONFIGURATION.md; for the environment variable list, see .env.example.

Security Notes

• By default, it only listens on 127.0.0.1 and is not exposed to the public network

• Do not commit secrets from config.json, .env, or logs to the code repository

• The QQ webmail sid for a single email expires with the login session; event details provide two reliable entry points: "Open in QQ Mail" and "Download Raw Email"

Testing

python -m unittest discover -s tests -v