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 以进行本地设置。将 config/auth.example.toml 复制到 config/auth.toml 以进行 OAuth 应用设置。请确保本地配置文件对您的用户账户保密。

本地文件的推荐权限：

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 配置

将 MCP 服务器添加到 ~/.codex/config.toml：

[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 的“移动和桌面应用程序 / 重定向 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 邮箱中获取最新的五条邮件主题：

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

暴露给 Codex 的等效 MCP 工具是：

microsoft_recent_messages(account_id, limit=5)

Gmail 设置

使用 Google Cloud 项目获取 Gmail API 和 OAuth 桌面凭据。

1. 打开 Google Cloud 控制台：

   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 收件箱主题：

.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 和日历读取。

• 轮换任何曾经以明文形式存储在配置中的个人访问令牌。