MailCal

Локальный почтовый календарь-помощник: читает почтовый ящик через IMAP, автоматически преобразует собеседования, тесты, встречи и сроки из писем в события календаря, предоставляет HTML-интерфейс календаря, а также одновременно открывает REST API и MCP для вызова такими инструментами, как Codex.

Блог-руководство

Подробное руководство: Руководство по спасению осеннего набора: превратите QQ Mail в AI-календарь с помощью MailCal, собеседования и тесты автоматически попадают в расписание

Настройка авторизационного кода QQ Mail: Учебник по настройке IMAP для QQ Mail

Открытый исходный код и контакты

MailCal имеет открытый исходный код; приветствуются звёзды и отчёты об Issue.

• GitHub-репозиторий: GlenYe-Coding/MailCal

• QQ-группа: 686046608 · Нажмите, чтобы присоединиться к группе MailCal

Возможности

• Инкрементальная синхронизация почты: позиция синхронизации записывается с помощью UID-курсора, обрабатываются только новые письма

• Очистка писем: преобразование HTML в обычный текст, удаление скриптов и стилей, сохранение ссылок для анализа

• Извлечение событий: механизм правил + LangGraph Agent определяют, нужно ли создавать задачу из письма

• Интерфейс календаря: месячный/недельный вид, статусы событий, всплывающие сводки, отображение исходного текста письма

• Административная консоль: журналы, использование токенов, статистика писем, очистка кэша

• Два интерфейса: 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

Полные ограничения параметров см. в 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 и ключи из журналов в репозиторий кода

• sid отдельного письма в веб-версии QQ Mail теряет силу вместе с состоянием входа; в деталях события предусмотрены два надёжных входа: «Открыть QQ Mail» и «Скачать исходное письмо»

Тестирование

python -m unittest discover -s tests -v