personal-mail-mcp

Локальный MCP-сервер для доступа Codex к личным почтовым ящикам и календарям.

Он подключает Codex к Microsoft Graph и Gmail, чтобы локальный помощник мог просматривать входящие письма, искать подтверждения встреч, создавать или обновлять записи в календаре, находить непрочитанные письма, которые могли быть пропущены вне папки «Входящие», и составлять безопасные планы архивации для малоценных сообщений. Проект также включает навыки Codex для повторяющихся рабочих процессов, таких как сбор встреч, сортировка входящих, проверка пропущенных писем и полный обзор почты.

Этот проект предоставляется «как есть». Он работает в моей собственной настройке, но не был широко протестирован с другими учетными записями, арендаторами, почтовыми провайдерами или конфигурациями Outlook/Gmail.

Текущие цели:

• Почтовые ящики и календари Exchange, размещенные на GoDaddy, через Microsoft Graph.

• Gmail через Google API.

• Инструменты аудита/планирования только для чтения, а также инструменты для явной архивации и записи в календарь.

Не следует коммитить секреты 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 — это учетные записи Exchange Online, доступные через Microsoft Graph. Специфический API GoDaddy не требуется.

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

   Это отображается в разделе «Мобильные и настольные приложения / 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

Создайте 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

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

Эквивалентный инструмент MCP, представленный в Codex:

microsoft_recent_messages(account_id, limit=5)

Настройка Gmail

Используйте проект Google Cloud для API Gmail и настольных учетных данных 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. Загрузите JSON клиента OAuth и сохраните его локально:

   <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

   Откройте выведенный URL-адрес Google, войдите в систему с настроенным тестовым пользователем и одобрите области чтения/изменения 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

Эквивалентный инструмент MCP, представленный в Codex:

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

Создайте план архивации для пробного запуска. Он возвращает только кандидатов на архивацию, сгруппированных по всем запрошенным учетным записям по причине архивации, отправителю и нормализованной теме. Каждое сообщение включает идентификатор учетной записи, идентификатор сообщения, тему, отправителя и дату получения:

.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

Архивируйте выбранные сообщения по идентификатору:

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

Эквивалентные инструменты MCP, представленные в Codex:

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. Когда один и тот же шаблон архивации появляется более одного раза или в нескольких учетных записях, план также возвращает рекомендации по фильтрам, которые можно использовать для создания правил почтового ящика/провайдера для будущих сообщений.

Удаленное создание фильтров/правил возможно, но требует дополнительных областей 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.

• Учетные данные клиента Gmail в .private/ и кэши токенов в .tokens/ должны иметь режим 600 для файлов и 700 для каталогов.

• Для текущих инструментов архивации/календаря требуются Mail.ReadWrite для Microsoft, gmail.modify для Google и Calendars.ReadWrite для Microsoft. Ограничьте регистрацию приложения только теми делегированными разрешениями, которые вы используете.

• Относитесь к archive_messages и инструментам изменения календаря как к действиям записи. Предпочитайте mail_archive_plan и чтение календаря перед применением изменений.

• Ротируйте любые личные токены доступа, которые когда-либо хранились в конфигурации в виде открытого текста.