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

전체 파라미터 제약은 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