MailCal

ローカルメールカレンダー管理ツール：IMAPでメールボックスを読み取り、メール内の面接、評価、締切日などのイベントを自動的に抽出してカレンダーイベントに変換し、HTMLカレンダーインターフェースを提供するとともに、REST APIとMCPを公開し、Codexなどのツールから呼び出せるようにします。

ブログチュートリアル

詳細チュートリアル：就活自救ガイド：MailCalでQQメールをAIカレンダーに変え、面接・評価を自動でスケジュール化

QQメール認証コード設定：QQメールIMAP設定チュートリアル

オープンソースと連絡先

MailCalはオープンソースです。StarとIssueでのフィードバックを歓迎します。

• GitHub：GlenYe-Coding/MailCal

• QQグループ：686046608・クリックしてQQグループに参加

機能

• 増分同期：UIDカーソルで同期位置を記録し、新着メールのみ処理

• メールクリーニング：HTMLをプレーンテキストに変換、スクリプト・スタイルを削除、リンクは分析用に保持

• イベント抽出：ルールエンジン＋LangGraphエージェントで、メールにTODO作成が必要か判断

• カレンダーインターフェース：月表示／週表示、イベントステータス、ホバー概要、メール原文レンダリング

• 管理コンソール：ログ、トークン使用量、メール統計、キャッシュクリア

• デュアルインターフェース：REST API＋MCP、ローカルサービスまたはCodexからの接続に対応

• モデル対応：OpenAI、DeepSeek、Kimi、GLM、Qwen、SiliconFlow、Ollama、カスタムOpenAI互換サービス

ドキュメント

• ドキュメント索引：MailCal全ドキュメントの入口

• APIドキュメント：RESTインターフェース、リクエストパラメータ、レスポンス形式、エラー仕様

• MCPドキュメント：MCPツール、パラメータ仕様、Codex接続方法

• アーキテクチャドキュメント：システム概要、同期パイプライン、ステートマシン

• 設定ドキュメント：config.json、環境変数、キャッシュとモデル設定

• クリーニングワークフロー：メールからイベントへの標準化処理フロー

• JSONスキーマ：メール、イベント、モデル出力形式

プロジェクト構成

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

完全なパラメータ仕様は 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キーは、インターフェース応答ではマスク形式でのみ表示されます。

詳細なフィールドは docs/CONFIGURATION.md を、環境変数の一覧は .env.example を参照してください。

セキュリティ注意事項

• デフォルトでは 127.0.0.1 のみをリッスンし、公網には公開しません

• config.json、.env、ログ内の秘密鍵をコードリポジトリにコミットしないでください

• QQウェブメールの各メールの sid はログイン状態の失効に伴い無効になります。イベント詳細には「QQメールを開く」と「元メールをダウンロード」の2つの信頼できる入口を提供しています

テスト

python -m unittest discover -s tests -v