email-mcp

Электронная почта и календарь через классический Outlook для Windows, управляемый через нативный COM (pywin32). Поставляется как одна команда email, которая является одновременно CLI и stdio MCP-сервером. Никакой регистрации приложения в Azure, никакого OAuth, никакого PowerShell — просто управляет настольным клиентом Outlook, в который вы уже вошли.

Требования

• Windows 10/11

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

• Python 3.10+ и uv

«Новый» Outlook для Windows не предоставляет COM. Если вы используете новый Outlook и не можете вернуться к классическому, этот инструмент не будет работать.

COM доступен только через настольный клиент Outlook — отдельной аутентификации нет. Какая учётная запись вошла в Outlook, ту и видит инструмент, а отправленные письма попадают в настоящую папку «Отправленные» точно так же, как если бы вы отправили их вручную.

Related MCP server: outlook-mcp

Установка / Запуск

Запуск прямо из GitHub с помощью uvx (без клонирования и ручной установки):

uvx --from git+https://github.com/kerodkibatu/email-mcp email --help

uv разрешает и кэширует пакет при первом запуске; последующие вызовы выполняются быстро.

CLI

Каждый инструмент — это подкоманда email. Вывод — JSON в stdout.

# List configured Outlook accounts
uvx --from git+https://github.com/kerodkibatu/email-mcp email list-accounts

# Query across all mail folders with a MongoDB-style filter (JSON string)
uvx --from git+https://github.com/kerodkibatu/email-mcp email query \
  --filter '{"$and":[{"from":{"$contains":"@kyros.com"}},{"unread":true}]}' \
  --limit 20 --order-by received_desc

# Read one email by EntryID
uvx --from git+https://github.com/kerodkibatu/email-mcp email read --entry-id "0000000..."

# Send a new mail (account is REQUIRED — see below)
uvx --from git+https://github.com/kerodkibatu/email-mcp email send \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

# Save a new mail as a draft instead of sending (same flags as send, no --send-as)
uvx --from git+https://github.com/kerodkibatu/email-mcp email draft \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

MCP

email mcp запускает stdio MCP-сервер, предоставляющий все 11 инструментов. Добавьте его в свой .mcp.json (или claude_desktop_config.json):

{
  "mcpServers": {
    "email": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kerodkibatu/email-mcp", "email", "mcp"]
    }
  }
}

Первый запуск медленнее, пока uv разрешает пакет; последующие запуски используют кэш.

Инструменты

Выбор учётной записи для отправки

send_email, reply_email и forward_email требуют параметр account — подстроку имени настроенной учётной записи Outlook (обычно SMTP-адрес). Это сделано намеренно: при наличии нескольких учётных записей (например, личной и рабочей) использование основной учётной записи Outlook по умолчанию — это ловушка: так личная почта может утечь из рабочей учётной записи или наоборот. Принудительное указание учётной записи делает отправку явной.

Если указанный account не соответствует ни одной настроенной учётной записи (без учёта регистра, подстрока), инструмент выдаёт ошибку и перечисляет доступные учётные записи. Сначала выполните list_accounts, если вы не знаете имя. Транспортная учётная запись задаётся непосредственно в элементе Outlook через SendUsingAccount.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "kerod@towlydigital.com"
}

Отправить как (ЭКСПЕРИМЕНТАЛЬНО — требуется разрешение Exchange «Отправить как»)

ЭКСПЕРИМЕНТАЛЬНО. Это работает только через классический Outlook с pywin32 COM — нет пути через Azure/OAuth. Поведение зависит от политики клиента: письмо может быть отклонено, молча понижено или остаться в «Исходящих». Воспринимайте это как попытку без гарантий.

send_email, reply_email и forward_email принимают необязательный параметр send_as — SMTP-адрес, от имени которого отправляется письмо. Получатель видит этот адрес как «От», без указания «от имени». Это настоящая функция Exchange «Отправить как», отличающаяся от «Отправить от имени».

Механически инструмент устанавливает SendUsingAccount на указанный вами account (транспортный почтовый ящик), затем разрешает send_as через Exchange и перезаписывает оба свойства MAPI PR_SENT_REPRESENTING_* и PR_SENDER_* (через PropertyAccessor элемента), чтобы они указывали на этот адрес перед отправкой. Перезапись свойств отправителя — а не только свойств «от имени» — превращает «от имени» в чистое «Отправить как». Exchange проверяет разрешение в момент отправки.

Требования:

• Пользователь account должен иметь разрешение «Отправить как» на почтовый ящик send_as, предоставленное на стороне сервера администратором Exchange. Инструмент не может предоставить или проверить это — он может только попытаться отправить.

• Адрес send_as должен разрешаться в Exchange — обычно это почтовый ящик в том же клиенте. Внешние адреса (gmail.com и т. п.) завершатся ошибкой при разрешении.

• Если разрешение отсутствует, поведение зависит от политики клиента: Exchange может отклонить письмо, молча понизить его до «от имени» или оставить в «Исходящих».

• Эта функция работает только внутри организации Exchange, которая явно её разрешила. Её нельзя использовать для подделки внешних отправителей.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "admin@custom.com",
  "send_as": "contact@custom.com"
}

Ответ включает поле sent_as, повторяющее адрес, если использовался send_as.

Отправка вложений

send_email принимает необязательный массив attachments с абсолютными путями к файлам. Каждый путь должен существовать и указывать на обычный файл; если какой-либо путь недействителен, инструмент возвращает ошибку со списком проблемных путей и не отправляет письмо. Прямые и обратные слэши принимаются в Windows; ~ и переменные окружения не раскрываются — передавайте полностью разрешённые пути.

{
  "to": "kerod@example.com",
  "subject": "Signed contract",
  "body": "See attached.",
  "account": "kerod@towlydigital.com",
  "attachments": [
    "C:\\Users\\Kerod\\Desktop\\contract.pdf",
    "C:/Users/Kerod/Desktop/cover-letter.pdf"
  ]
}

Загрузка вложений

Инструмент download_attachments извлекает файлы из письма и сохраняет их локально, возвращая абсолютный путь к папке.

• Расположение: Файлы сохраняются в папке «Загрузки» пользователя: ~/Downloads/email-attachments/YYYY-MM-DD_отправитель-slug_тема-slug/.

• Встроенные изображения: Логотипы и изображения подписей по умолчанию отфильтровываются, чтобы избежать беспорядка. Установите include_inline: true, если они вам нужны.

• Идемпотентность: Повторный запуск инструмента для того же письма безопасно использует ту же папку (отслеживается через маркер .entry_id) и устраняет неоднозначность, когда два разных письма имеют одинаковый slug.

Как это работает

Команда email подключается к запущенному экземпляру Outlook через COM (если он не запущен, запускает его), затем управляет пространством имён MAPI для чтения и записи почты. Весь COM-доступ проходит через один сеанс Outlook; инструмент никогда не запускает PowerShell.

Это означает:

• Outlook должен быть установлен (не обязательно открыт — первый вызов запустит его)

• Какая учётная запись вошла в Outlook, ту и видит инструмент — отдельной аутентификации нет

• Отправленные письма появляются в папке «Отправленные» пользователя точно так же, как если бы они были отправлены вручную

Лицензия

MIT — см. LICENSE.