Apple Mail MCP Server

MCP-сервер, обеспечивающий программный доступ к Apple Mail, позволяющий ИИ-ассистентам, таким как Claude, читать, отправлять, искать и управлять электронной почтой на macOS.

⚠️ До версии 1.0 — возможны критические изменения. Поверхность инструментов MCP (имена инструментов, параметры, форматы возвращаемых данных) всё ещё развивается по мере взросления проекта. Закрепитесь на конкретной версии (например, apple-mail-mcp==0.10.2) и просмотрите CHANGELOG перед обновлением.

Инструменты (29)

Сгруппированы по жизненному циклу (10 только для чтения, 19 изменяющих):

• Обнаружение — list_accounts, list_mailboxes, list_rules, list_templates: перечисление того, что настроено (без внешнего кэша — вызывайте для каждой учётной записи).

• Чтение — search_messages, get_messages, get_thread, get_attachment_content, get_template, render_template: чтение сообщений/цепочек, получение содержимого вложения встроенно и рендеринг шаблонов.

• Действия с сообщениями — update_message (прочитать/пометить/переместить за один проход), delete_messages (→ в Корзину), save_attachments (на диск, с ограничением по байтам).

• Черновики — create_draft (новый / ответ / пересылка, опционально send_now), update_draft, delete_draft.

• Прямая отправка — send_email, reply, reply_all, forward: отправка одним вызовом, без промежуточного черновика. Каждый из них отправляет по-настоящему; в Mail нет второго шага подтверждения.

• Учётные записи — delete_account: удаление настроенной учётной записи из Mail.app.

• CRUD для почтовых ящиков — create_mailbox, update_mailbox (переименование или перемещение), delete_mailbox.

• Правила — create_rule, update_rule, delete_rule.

• Шаблоны (запись) — save_template, delete_template.

Деструктивные операции (delete_*, create_rule с действиями перемещения/пересылки/удаления, create_draft с send_now=true) запрашивают подтверждение через механизм запроса MCP. Полные параметры и форматы возвращаемых данных см. в docs/reference/TOOLS.md.

Related MCP server: apple-mail-mcp

Предварительные требования

• macOS 10.15 (Catalina) или новее

• Python 3.10 или новее

• Apple Mail, настроенный как минимум с одной учётной записью

• uv (рекомендуется) или pip

Установка

# From source (recommended for development)
git clone https://github.com/LeChabrax/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

Конфигурация

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json). uv sync устанавливает консольный скрипт в .venv/bin/apple-mail-mcp; укажите Claude Desktop его абсолютный путь — это самая надёжная форма в ограниченной среде запуска Claude Desktop (без зависимости от uv в PATH):

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

(Эквивалентная альтернатива, если вы предпочитаете запускать через uv: "command": "uv", "args": ["--directory", "/path/to/apple-mail-mcp", "run", "apple-mail-mcp"].)

Опционально: разделение серверов чтения/записи

Claude Desktop запрашивает разрешение для каждого инструмента. Если вы хотите пакетно одобрить 10 инструментов чтения (list / search / get) и при этом по-прежнему ограничивать 19 изменяющих инструментов по отдельности, запустите коннектор дважды — один раз с --read-only, второй раз без — под двумя отдельными записями mcpServers:

{
  "mcpServers": {
    "apple-mail-read": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp",
      "args": ["--read-only"]
    },
    "apple-mail-write": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

Сервер с --read-only предоставляет только 10 инструментов чтения, поэтому пользовательский интерфейс разрешений Claude Desktop для каждого сервера естественным образом группирует их. Полный сервер по-прежнему ограничивает записи по отдельности. Компромисс: 2× процесса коннектора. См. docs/reference/TOOLS.md для классификации по инструментам и примечание о подсказках аннотаций MCP (readOnlyHint / destructiveHint / idempotentHint), которые совместимые с будущими версиями хосты могут использовать для обеспечения того же UX без разделения.

Разрешения

При первом запуске macOS запросит доступ к автоматизации. Предоставьте разрешение в: Системные настройки > Конфиденциальность и безопасность > Автоматизация > Терминал (или ваша IDE)

Опционально: более быстрый поиск через IMAP

search_messages работает из коробки через AppleScript. Для больших почтовых ящиков (тысячи сообщений) предложение whose в AppleScript может занимать 1–5 секунд на запрос. Если вы хотите более быстрый серверный поиск, вы можете включить делегирование IMAP для каждой учётной записи, добавив запись в связку ключей.

Как это работает. Если для учётной записи существуют учётные данные, сервер использует IMAP (быстрый серверный SEARCH). В противном случае — или при любой ошибке IMAP (офлайн, неверный пароль, тайм-аут) — он незаметно переключается на AppleScript. Вы никогда не теряете функциональность; вы только получаете скорость, когда IMAP настроен и доступен. Обычный способ включения — запись в связке ключей (ниже); запасной вариант через переменную окружения (далее) покрывает контексты, где связка ключей недоступна.

Одноразовая настройка для каждой учётной записи.

1. Сгенерируйте пароль приложения у вашего провайдера. Процедура различается:

   • iCloud: appleid.apple.com/account/manage → Пароли приложений. Требуется двухфакторная аутентификация для вашего Apple ID (по умолчанию).

   • Gmail: myaccount.google.com/apppasswords. Требуется двухэтапная проверка для вашей учётной записи Google.

   • Yahoo / Fastmail / AOL: сгенерируйте пароль приложения в настройках безопасности учётной записи провайдера.

2. Запустите подкоманду setup-imap. Она запрашивает пароль (без эха), записывает запись в связку ключей и проверяет подключение:

   apple-mail-mcp setup-imap --account iCloud

   Подставьте точное имя учётной записи Mail.app — как оно указано в Mail.app (например, iCloud, Gmail, "Yahoo!"). CLI:

   • определяет основной email учётной записи из Mail.app (переопределите с помощью --email, который сохраняется, чтобы во время выполнения использовался тот же логин — см. особенность iCloud ниже),

   • запрашивает через getpass, чтобы пароль никогда не попадал в историю оболочки,

   • записывает в связку ключей по адресу apple-mail-mcp.imap.<account> (идемпотентно — повторный запуск с новым паролем обновляет существующую запись),

   • открывает IMAP-соединение и выполняет реальный LOGIN для подтверждения работоспособности пароля. При отклонении он откатывает запись в связке ключей, чтобы вы могли повторить попытку, не оставляя повреждённого элемента.

3. Если при следующем вызове на основе IMAP появится одноразовое окно "security wants to use the 'login' keychain", нажмите Always Allow.

Чтобы удалить запись позже: apple-mail-mcp setup-imap --account iCloud --uninstall.

Запасной вариант через переменную окружения (uvx / headless / CI)

В некоторых контекстах нет пригодной связки ключей: запуски uvx (эфемерные пути к бинарным файлам нарушают ACL связки ключей, вызывая повторные запросы или сбои), Docker / CI (вообще нет связки ключей) и фоновые службы (запрос ACL блокируется навсегда без привязанного интерфейса). Для таких случаев вы можете указать пароль IMAP через переменную окружения:

APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>

<SUFFIX> — это имя учётной записи Mail.app в верхнем регистре, где каждая последовательность неалфавитно-цифровых символов сжимается в одно подчёркивание, а ведущие/замыкающие подчёркивания удаляются:

Если задано непустое значение, переменная окружения используется в приоритете над любой записью в связке ключей для этой учётной записи (она проверяется первой, без вызова security). Пустое значение или значение из пробелов игнорируется, и используется путь через связку ключей. Поиск сочетается с запасным вариантом имя↔UUID, поэтому переменная окружения, ключом которой является имя учётной записи, всё равно находится, когда вызывающий передаёт UUID учётной записи.

⚠️ Компромисс безопасности. Переменные окружения гораздо менее приватны, чем связка ключей — они видны через ps -E, launchctl getenv, интроспекцию в стиле /proc и дампы памяти процессов, и их легко утечь в журналы или историю оболочки. Используйте это только тогда, когда связка ключей действительно недоступна (uvx, Docker, CI, headless). Для Claude Desktop и стандартных локальных установок придерживайтесь setup-imap + связка ключей.

Примечание: сопоставление имя→суффикс необратимо — Yahoo! и Yahoo оба отображаются в YAHOO, а имя учётной записи без букв/цифр ASCII не имеет формы переменной окружения (для таких используйте связку ключей).

Проверка настройки. Команда setup-imap делает это за вас. Если вы хотите проверить вручную:

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

Если IMAP работает, вызов возвращается за ~1 секунду. Если он регистрирует WARNING о переходе на запасной вариант (видно с --log-level=DEBUG), проверьте, что имя учётной записи точно совпадает с именем в Mail.app и что email в вашей записи связки ключей соответствует тому, что возвращает email addresses of account.

Известные особенности провайдеров.

• iCloud: IMAP-сервер принимает псевдонимы @icloud.com / @me.com в качестве имени пользователя LOGIN, а не email Apple ID. Сервер (и setup-imap) по этой причине читает email addresses of account из Mail.app. Если ваш Apple ID iCloud — сторонний адрес (например, Apple ID на @gmail.com) и Mail.app не сообщает адрес @icloud.com для учётной записи, автоопределение не может найти правильный логин — setup-imap завершится с подсказкой повторить с --email <ваш адрес @icloud.com/@me.com>. Это значение --email сохраняется (в ~/.apple_mail_mcp/imap_login_overrides.json), чтобы разрешение во время выполнения использовало тот же логин (#341). Это общее переопределение — используйте его для любой учётной записи, у которой автоопределённый IMAP-логин неверен.

• Yahoo: пароли приложений постепенно упраздняются; опция может быть недоступна для всех учётных записей. Если на странице безопасности учётной записи Yahoo нет этой опции, настройка IMAP для этой учётной записи невозможна, и остаётся только AppleScript.

• Gmail: требуется включённая двухэтапная проверка. Если администратор Google Workspace отключил пароли приложений на уровне тенанта, настройка IMAP для этой учётной записи невозможна.

• Gmail — получение цепочек: компромисс видимости All Mail. find_thread_members (используемый внутренне запросами, учитывающими цепочки) работает быстрее всего, когда [Gmail]/All Mail доступен через IMAP — этот путь занимает ~5 круговых обменов, независимо от количества почтовых ящиков. Многие пользователи скрывают All Mail (Настройки Gmail → Пересылка и POP/IMAP → Ограничения размера папок → "Не показывать в IMAP"), потому что он дублирует каждое сообщение. Когда он скрыт, коннектор переключается на итерацию X-GM-THRID по каждому почтовому ящику (всё ещё ~6× быстрее универсального BFS, но пропорционально количеству меток — ~25 секунд для учётной записи с 92 метками). Откройте All Mail, если хотите максимальную скорость; оставьте скрытым, если предпочитаете более чистый список папок IMAP.

Операции записи (create_draft, update_draft, включая путь отправки с send_now=true) всегда используют AppleScript независимо от конфигурации IMAP — им нужен интерфейс создания сообщений Mail.app.

Тайм-ауты для очень больших почтовых ящиков

Значения по умолчанию рассчитаны на обычные почтовые ящики, и их стоит увеличить на большом почтовом ящике. Собственные измерения этого модуля: 148 секунд для 100 сообщений с холодным кэшем в почтовом ящике на 47 тысяч сообщений, поэтому серверный SEARCH там может превысить 30-секундный тайм-аут по умолчанию и незаметно переключиться на более медленный путь AppleScript.

Нечисловое или неположительное значение игнорируется с предупреждением, и сохраняется значение по умолчанию, так что опечатка не может вывести сервер из строя.

Разработка

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

Соглашение о ветках

{type}/issue-{num}-{description} — например, feature/issue-42-thread-support

Архитектура

server.py (FastMCP tools — thin orchestration, validation, elicitation gates)
  -> mail_connector.py (dispatch + domain logic)
     -> AppleScript path:  subprocess.run(["osascript", ...]) -> Apple Mail.app   (universal baseline)
     -> IMAP fast path:    imap_connector.py -> the account's IMAP server          (when hinted + Keychain creds)

Dispatch model. AppleScript — это всегда доступный базовый вариант. Когда вызов чтения/изменения передаёт подсказку account (и, где применимо, mailbox) и для учётной записи есть учётные данные IMAP в связке ключей (Keychain), коннектор использует быстрый путь IMAP на стороне сервера; при любой ошибке IMAP он возвращается к AppleScript, так что вы никогда не теряете функциональность — вы только выигрываете в скорости. Полное описание модели диспетчеризации, схемы двойной эмиссии message-ID, жизненного цикла черновиков и уровней потоков IMAP см. в docs/reference/ARCHITECTURE.md.

• server.py — регистрация инструментов MCP, проверка входных данных, шлюзы подтверждения (elicitation), форматирование ответов

• mail_connector.py — генерация/выполнение AppleScript + диспетчеризация по быстрому пути IMAP

• imap_connector.py — IMAP-клиент + пул соединений (быстрые пути поиска, выборки, массовых изменений)

• security.py — санитизация входных данных, аудит-логирование, потоки подтверждения

• utils.py — чистые функции: экранирование, разбор, валидация

• exceptions.py — иерархия типизированных исключений

Безопасность

• Только локальное выполнение (без облачной обработки)

• Использует существующую аутентификацию Mail.app; пароли приложений IMAP (по желанию) хранятся в связке ключей macOS, никогда в репозитории или конфигурации

• Все входные данные санитизируются и экранируются для AppleScript (защита от инъекций AppleScript)

• Деструктивные операции требуют подтверждения пользователя через MCP elicitation; сверх того — ограничения скорости и аудит-логирование

• save_attachments ограничен по байтам (на вложение + суммарно) для защиты от DoS-заполнения диска

Документация:

• SECURITY.md — политика сообщения об уязвимостях

• docs/SECURITY.md — безопасность и конфиденциальность для пользователей

• docs/guides/THREAT_MODEL.md — анализ границ доверия по STRIDE

• docs/guides/SECURITY_CHECKLIST.md — чек-лист контрибьютора по каждой функции

Участие

О процессе разработки, стандартах кодирования и порядке PR см. CONTRIBUTING.md.

Благодарности

Этот проект — форк apple-mail-mcp Моргана Джеффриса, который выполняет всю основную работу: мост AppleScript, быстрый путь IMAP, хранилище состояния черновиков, шаблоны и шлюзы elicitation.

Что этот форк добавляет поверх апстрима v0.10.2:

Всё остальное, включая набор инструментов, тесты и документацию, взято из апстрима. Баг-репорты об общих частях лучше подавать туда.

Что Mail.app не позволит этому серверу сделать

Проверено на macOS 15, стоит знать перед открытием issue:

• Учётная запись, созданная через AppleScript, никогда не сохраняется. make new imap account возвращает идентификатор, и count of accounts видит её, но она отсутствует в окне настроек Mail и исчезает после выхода из Mail. Для реального добавления учётной записи нужен профиль конфигурации (com.apple.mail.managed), одобренный на экране. Скриптового пути нет: profiles install отвечает "profiles tool no longer supports installs".

• enabled нельзя записать ни для одной учётной записи. set enabled вызывает -10000 AppleEvent handler failed — и для новой, и для существующей активной учётной записи, через AppleScript и через JXA, при любой форме ссылки. Собственный sdef Mail объявляет свойство доступным для записи (нет access="r", cocoa-ключ isActive); реализация с этим не согласна.

• Окно настроек Mail — устаревший снимок. В нём перечислены учётные записи, о которых AppleScript уже не знает, и отсутствуют те, о которых он знает. Никогда не читайте состояние учётных записей из интерфейса.

Лицензия

MIT