personal-mail-mcp

개인 메일 및 캘린더 계정에 대한 Codex 액세스를 위한 로컬 MCP 서버입니다.

이 서버는 Codex를 Microsoft Graph 및 Gmail에 연결하여 로컬 어시스턴트가 받은 편지함 메일을 검토하고, 약속 확인 메일을 스캔하며, 캘린더 항목을 생성하거나 업데이트하고, 받은 편지함 외부에서 놓쳤을 수 있는 읽지 않은 메일을 찾고, 가치가 낮은 메시지에 대한 안전한 보관 계획을 세울 수 있도록 합니다. 또한 이 프로젝트에는 약속 수집, 받은 편지함 분류, 놓친 메일 검토, 전체 메일 검토와 같은 반복적인 워크플로우를 위한 Codex 기술이 포함되어 있습니다.

이 프로젝트는 있는 그대로 제공됩니다. 제 개인 설정에서는 작동하지만, 다른 계정, 테넌트, 메일 제공업체 또는 Outlook/Gmail 구성 전반에 걸쳐 광범위하게 테스트되지는 않았습니다.

현재 대상:

• Microsoft Graph를 통한 GoDaddy 호스팅 Exchange 사서함 및 캘린더.

• Google API를 통한 Gmail.

• 읽기 전용 감사/계획 도구 및 명시적 보관 및 캘린더 쓰기 도구.

OAuth 비밀 정보나 토큰 캐시는 커밋해서는 안 됩니다. 로컬 설정을 위해 config/accounts.example.toml을 config/accounts.toml로 복사하십시오. OAuth 앱 설정을 위해 config/auth.example.toml을 config/auth.toml로 복사하십시오. 로컬 구성 파일은 사용자 계정에서만 비공개로 유지하십시오.

로컬 전용 파일에 권장되는 권한:

chmod 700 .private .tokens
chmod 600 config/accounts.toml config/auth.toml config/mail_rules.local.toml

로컬 프로젝트 설정

로컬 환경을 생성하고 설치하십시오:

cd <repo-path>
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[providers]'

Codex 구성

~/.codex/config.toml에 MCP 서버를 추가하십시오:

[mcp_servers.personal_mail]
type = "stdio"
command = "<repo-path>/.venv/bin/python"
args = ["-m", "personal_mail_mcp.server"]
startup_timeout_sec = 30

구성을 변경한 후 Codex를 다시 시작하여 활성 도구 목록에 MCP 서버가 나타나도록 하십시오.

계정 구성

config/accounts.toml을 생성하십시오:

[[accounts]]
id = "exchange_primary"
provider = "microsoft"
email = "primary@example.com"
calendar = true

[[accounts]]
id = "exchange_secondary"
provider = "microsoft"
email = "secondary@example.com"
calendar = false

[[accounts]]
id = "google_primary"
provider = "google"
email = "public-example@gmail.com"
calendar = false

이 파일은 git에서 무시됩니다.

Microsoft 앱 등록

GoDaddy 계정은 Microsoft Graph를 통해 액세스할 수 있는 Exchange Online 계정입니다. GoDaddy 전용 API는 필요하지 않습니다.

1. Microsoft Entra 관리 센터를 엽니다:

   https://entra.microsoft.com/

2. 다음으로 이동합니다:

   Entra ID > App registrations > New registration

   왼쪽 탐색 메뉴가 다른 경우 포털 검색 상자에서 App registrations를 검색하십시오.

3. 앱을 등록합니다:

   Name: personal-mail-mcp
   Supported account types: Single tenant only - your Microsoft 365 tenant

4. 앱 등록 개요 페이지에서 다음을 복사하십시오:

   Application (client) ID
   Directory (tenant) ID

5. 인증 아래에서 네이티브/로컬 앱에 대한 리디렉션 URL을 추가하십시오:

   http://localhost

   이는 현재 포털 UI의 Mobile and desktop applications / Redirect URLs 아래에 나타납니다.

6. 인증 설정 아래에서 공용/네이티브 클라이언트 흐름을 활성화하십시오. 포털 문구는 다음 중 하나일 수 있습니다:

   Allow public client flows
   Enable the following mobile and desktop flows
   Treat application as a public client

   Yes로 설정하고 저장하십시오.

7. API 권한 아래에서 Microsoft Graph 위임 권한을 추가하십시오:

   Mail.Read
   Mail.ReadWrite
   Calendars.ReadWrite
   offline_access

복사한 ID로 config/auth.toml을 생성하십시오:

[microsoft]
client_id = "APPLICATION_CLIENT_ID_FROM_ENTRA"
tenant = "DIRECTORY_TENANT_ID_FROM_ENTRA"

[google]
client_secrets_file = ".private/google-oauth-client.json"

이 파일에 OpenAI, ChatGPT, Codex 또는 GitHub 토큰을 넣지 마십시오. 이 파일은 git에서 무시됩니다.

Exchange Online 계정 연결

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli status
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_primary
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_secondary

각 연결 명령은 Microsoft 장치 코드 URL과 코드를 출력합니다. URL을 열고 코드를 입력한 다음 일치하는 계정으로 로그인하십시오:

exchange_primary   -> primary Exchange Online mailbox
exchange_secondary -> secondary Exchange Online mailbox

성공적으로 연결되면 git에서 무시되는 .tokens/ 아래에 로컬 토큰 캐시 파일이 기록됩니다.

확인:

.venv/bin/python -m personal_mail_mcp.cli status

Microsoft 계정은 다음을 표시해야 합니다:

token_cached: true

읽기 전용 확인

기본 Exchange 사서함에서 최신 메시지 제목 5개를 가져옵니다:

.venv/bin/python -m personal_mail_mcp.cli recent-messages exchange_primary --limit 5

Codex에 노출되는 해당 MCP 도구는 다음과 같습니다:

microsoft_recent_messages(account_id, limit=5)

Gmail 설정

Gmail API 및 OAuth 데스크톱 자격 증명에는 Google Cloud 프로젝트를 사용하십시오.

1. Google Cloud Console을 엽니다:

   https://console.cloud.google.com/

2. 프로젝트를 생성하거나 선택한 다음 다음을 활성화하십시오:

   Gmail API

3. 다음에서 OAuth 동의를 구성하십시오:

   Google Auth Platform > Branding

   personal-mail-mcp와 같은 간단한 앱 이름을 사용하십시오. 개인 Gmail 계정의 경우 External 대상을 사용하고 다음에서 테스트 사용자로 Gmail 주소를 추가하십시오:

   Google Auth Platform > Audience > Test users

4. 다음에서 데스크톱 OAuth 클라이언트를 생성하십시오:

   Google Auth Platform > Clients > Create client

   사용:

   Application type: Desktop app
   Name: personal-mail-mcp

5. OAuth 클라이언트 JSON을 다운로드하여 로컬에 저장하십시오:

   <repo-path>/.private/google-oauth-client.json

   권한을 강화하십시오:

   chmod 600 .private/google-oauth-client.json

6. config/auth.toml이 해당 파일을 가리키는지 확인하십시오:

   [google]
   client_secrets_file = ".private/google-oauth-client.json"

7. Gmail 계정을 연결하십시오:

   cd <repo-path>
   PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect google_primary

   출력된 Google URL을 열고 구성된 테스트 사용자로 로그인한 다음 Gmail 읽기/수정 범위를 승인하십시오.

8. 확인:

   .venv/bin/python -m personal_mail_mcp.cli status

   Gmail 계정은 다음을 표시해야 합니다:

   token_cached: true

최신 Gmail 받은 편지함 제목 3개를 가져옵니다:

.venv/bin/python -m personal_mail_mcp.cli recent-gmail google_primary --limit 3

Codex에 노출되는 해당 MCP 도구는 다음과 같습니다:

gmail_recent_messages(account_id, limit=5)

메일 분류

MCP 서버에는 재사용 가능한 받은 편지함 감사 및 보관 도우미가 포함되어 있어 반복적인 분류를 위해 임시 스크립트가 필요하지 않습니다.

계정 전반에 걸쳐 읽기 전용 감사를 실행하십시오:

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli audit-mail exchange_primary exchange_secondary google_primary --limit-per-account 250

드라이 런(dry-run) 보관 계획을 생성하십시오. 이는 보관 이유, 보낸 사람 및 정규화된 제목별로 요청된 모든 계정에 걸쳐 그룹화된 보관 후보만 반환합니다. 각 메시지에는 계정 ID, 메시지 ID, 제목, 보낸 사람 및 수신 날짜가 포함됩니다:

.venv/bin/python -m personal_mail_mcp.cli archive-plan exchange_primary exchange_secondary google_primary --limit-per-account 250

페이지 매김을 사용하여 단일 받은 편지함을 나열하십시오:

.venv/bin/python -m personal_mail_mcp.cli inbox exchange_primary --limit 100

보관되거나 규칙에 의해 이동된 메시지와 같이 받은 편지함 외부의 읽지 않은 메일을 스캔하십시오. 이 명령은 해당 메시지를 분류하고 명백한 보관/노이즈와 별도로 주의가 필요한 후보를 반환합니다:

.venv/bin/python -m personal_mail_mcp.cli missed-mail exchange_primary exchange_secondary google_primary --limit-per-account 100

ID별로 선택한 메시지를 보관하십시오:

.venv/bin/python -m personal_mail_mcp.cli archive-mail exchange_primary <message-id> [<message-id> ...]

Codex에 노출되는 해당 MCP 도구는 다음과 같습니다:

mail_inbox(account_id, limit=100)
mail_audit(account_ids, limit_per_account=250)
mail_archive_plan(account_ids, limit_per_account=250)
missed_mail(account_ids, limit_per_account=100)
archive_messages(account_id, message_ids)

감사 분류기는 의도적으로 결정론적입니다. 메일을 keep, flag, archive, review로 그룹화합니다. 메시지를 이동하기 전 일반적인 검토 단계로 mail_archive_plan을 사용하십시오. 이는 읽기 전용이며 archive_messages에 필요한 정확한 ID를 포함합니다. 동일한 보관 패턴이 두 번 이상 또는 여러 계정에 걸쳐 나타날 때, 계획은 향후 메시지에 대한 사서함/제공업체 규칙을 만드는 데 사용할 수 있는 필터 권장 사항도 반환합니다.

원격 필터/규칙 생성은 가능하지만 추가 OAuth 범위가 필요합니다. Microsoft Graph 메시지 규칙에는 MailboxSettings.ReadWrite가 필요하고, Gmail 필터 생성에는 gmail.settings.basic이 필요합니다. 해당 범위가 추가되고 승인될 때까지 서버는 필터를 생성하는 대신 권장만 해야 합니다.

재사용 가능한 기본값은 config/mail_rules.default.toml에 있습니다. 사용자별 보낸 사람, 보존 수 및 보관 패턴은 git에서 무시되는 config/mail_rules.local.toml에 속합니다. 로컬 재정의를 위한 템플릿으로 config/mail_rules.example.toml을 사용하십시오.

선택적 Codex 기술

이 프로젝트에는 공유 가능한 Codex 기술이 포함되어 있습니다:

skills/email-appointment-harvest
skills/inbox-triage
skills/missed-mail-review
skills/review-all-mail

이 기술은 최근 이메일을 스캔하고, 약속/캘린더 후보를 제안하고, 승인을 기다린 다음, 승인된 캘린더 항목만 생성하거나 업데이트하는 반복 가능한 워크플로우를 문서화합니다.

Codex 환경에 설치하십시오:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/email-appointment-harvest "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/inbox-triage "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/missed-mail-review "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/review-all-mail "${CODEX_HOME:-$HOME/.codex}/skills/"

설치 후 Codex를 다시 시작하십시오. 요청 예시:

Use email appointment harvest to scan the last 7 days of email for appointments,
propose calendar entries, and add only the entries I approve.

설치된 기술은 이 MCP 서버가 Codex에 구성되어 있고 메일/캘린더 OAuth 토큰이 이미 연결되어 있다고 가정합니다.

보안 참고 사항

• config/auth.toml, config/accounts.toml 및 .tokens/는 로컬 전용입니다.

• Microsoft 앱은 공용/네이티브 클라이언트입니다. 이 CLI 흐름을 위해 클라이언트 비밀을 생성하거나 저장하지 마십시오.

• .private/ 아래의 Gmail 클라이언트 자격 증명과 .tokens/ 아래의 토큰 캐시는 파일의 경우 600, 디렉토리의 경우 700 모드여야 합니다.

• 현재 보관/캘린더 도구에는 Microsoft Mail.ReadWrite, Google gmail.modify 및 Microsoft Calendars.ReadWrite가 필요합니다. 앱 등록 범위를 사용하는 위임된 권한으로만 제한하십시오.

• archive_messages 및 캘린더 변경 도구는 쓰기 작업으로 취급하십시오. 변경 사항을 적용하기 전에 mail_archive_plan 및 캘린더 읽기를 우선적으로 사용하십시오.

• 일반 텍스트 구성에 저장된 적이 있는 개인 액세스 토큰은 주기적으로 교체하십시오.