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

設定を変更した後は、MCPサーバーがアクティブなツールリストに表示されるようにCodexを再起動してください。

アカウントの設定

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では [モバイルおよびデスクトップアプリケーション] / [リダイレクトURL] の下に表示されます。

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

接続に成功すると、.tokens/ 配下にローカルのトークンキャッシュファイルが書き込まれます（gitによって無視されます）。

確認:

.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コンソールを開きます:

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

2. プロジェクトを作成または選択し、以下を有効にします:

   Gmail API

3. 以下でOAuth同意画面を設定します:

   Google Auth Platform > Branding

   personal-mail-mcp のような単純なアプリ名を使用してください。個人のGmailアカウントの場合は、[外部] オーディエンスを使用し、以下でテストユーザーとして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

最新の3件のGmail受信トレイの件名を取得します:

.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

ドライランのアーカイブ計画を作成します。これは、要求されたすべてのアカウントにわたって、アーカイブの理由、送信者、正規化された件名ごとにグループ化されたアーカイブ候補のみを返します。各メッセージには、アカウント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 にあります。ユーザー固有の送信者、保持数、アーカイブパターンは config/mail_rules.local.toml に属しており、これはgitによって無視されます。ローカルでの上書き用テンプレートとして 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 およびカレンダーの読み取りを優先してください。

• プレーンテキストの設定ファイルに保存されたことのある個人用アクセストークンはすべてローテーションしてください。