Apple Mail MCP Server

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

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

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

Основные: list_mailboxes, search_messages, get_messages, update_message Жизненный цикл черновиков: create_draft, update_draft, delete_draft CRUD почтовых ящиков: create_mailbox, update_mailbox, delete_mailbox Вложения и управление: save_attachments, delete_messages Обнаружение и правила: list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule Шаблоны: list_templates, get_template, save_template, delete_template, render_template

Полную документацию по параметрам и возвращаемым структурам смотрите в 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/s-morgan-jeffries/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

Настройка

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

Разрешения

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

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

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

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

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

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

   • iCloud: appleid.apple.com/account/manage → App-Specific Passwords. Требуется двухфакторная аутентификация (2FA) на вашем Apple ID (по умолчанию включено).

   • Gmail: myaccount.google.com/apppasswords. Требуется двухэтапная проверка (2-Step Verification) в вашем аккаунте Google.

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

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

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

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

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

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

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

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

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

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

Проверка настройки. Команда 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 и что адрес в вашей записи Keychain соответствует тому, возвращает email addresses of account.

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

• iCloud: IMAP-сервер принимает в качестве логина (LOGIN username) псевдонимы @icloud.com / @me.com, а не адрес Apple ID. Поэтому сервер (и setup-imap) читает email addresses of account из Mail.app.

• 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»), потому что All Mail дублирует каждое сообщение. Когда All Mail не будет дублироваться, коннектор переключается на перебор по X-GTX-THRID по каждому ящику (это всё ещё ~6 раз быстревобщего быстрого поиска BFS, но пропорционально числу ярлыков — около 25 секунд в аккаунте с 92 ярлыками). Покажите All Mail, если нужна максимальной скорость; оставьте её скрытой, если предпочитаете чистый список папок IMAP.

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

Development

# 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-und42-thread-support

Архитектура

server.py (FastMCP tools — thin orchestration)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py — регистрация инструментов MCP, проверка входных данных, форматирование ответов

• mail_connector.py — генерация и выполнение всех сценариев AppleScript

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

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

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

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

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

• Используется существующая аутентификация Mail.app (без хранения учётных данных)

• Все входные данные проходят санитизацию и экранирование для AppleScript

• Деструктивные операции требуют подтверждения

• Ведётся журнал аудита операций

• Политика — в SECURITY.md, подробный анализ — в docs/SECURITY.md

Участие в разработке

Процесс разработки, стандарты и процесс PR описаны в CONTRIBUTING.md.

Лицензия

MIT