# owa-mail-mcp

MCP-сервер для почты Microsoft Exchange / OWA. Даёт AI-ассистенту (Claude Code, Claude Desktop, Codex, Cursor, OpenCode, Kilo Code и любому stdio MCP-клиенту) доступ к почтовому ящику:

- **проверять почту:** новые и непрочитанные письма;
- **искать сообщения:** по тексту, отправителю, получателю, теме, датам, вложениям;
- **читать и суммаризировать треды:** вся переписка из «Входящих», «Отправленных» и других папок, по порядку, без процитированной истории;
- **находить отправителей:** кто пишет и сколько, кто ждёт ответа, поиск людей в адресной книге организации;
- **отправлять письма**, но только после того, как пользователь нажмёт «Отправить» в отдельном окне на своём компьютере.

Сайт с инструкцией: **https://khomiakov7706.github.io/owa-mail-mcp/** (также [English](https://khomiakov7706.github.io/owa-mail-mcp/en/), [中文](https://khomiakov7706.github.io/owa-mail-mcp/zh/), [Español](https://khomiakov7706.github.io/owa-mail-mcp/es/))

<p align="center"><img src="docs/confirm-light.png" alt="Окно подтверждения отправки" width="620"></p>

## Быстрый старт

macOS или Linux, одна команда в терминале:

```bash
curl -LsSf https://raw.githubusercontent.com/Khomiakov7706/owa-mail-mcp/main/install.sh | sh
```

Скрипт ставит [uv](https://docs.astral.sh/uv/) (менеджер Python от Astral), а через него — owa-mail-mcp в отдельное окружение на Python 3.12, который uv скачает сам. Системный Python не используется: на macOS это 3.9, а MCP SDK нужен 3.10+. Повторный запуск той же команды обновляет программу. Настройки при этом сохраняются: они лежат не в папке программы, а в `config.json` (см. ниже) и в системной связке ключей, поэтому установщик, увидев готовые настройки, окно не открывает. Если после обновления macOS спросит, разрешить ли доступ к связке ключей, нажмите «Всегда разрешать». Проверить, что всё на месте: `owa-mail-mcp status`. После обновления перезапустите MCP-сервер в клиенте (Claude Code: `/mcp` → owa-mail → Reconnect; Claude Desktop и Cursor: закрыть и открыть приложение): клиент держит запущенный процесс со старым кодом. Если забыть, ошибки инструментов сами подскажут, что нужен перезапуск, а `get_status` покажет версию и `restart_needed`. В конце открывается окно настройки. Если почта открывается только из корпоративной сети, включите VPN.

### Установка через агента

Агенту с терминалом на вашем компьютере (Claude Code, Codex, Cursor, OpenCode, Kilo Code) можно отправить:

```text
Установи и подключи MCP-сервер OWA Mail для моей рабочей почты Exchange.
Следуй инструкции для агентов шаг за шагом: https://khomiakov7706.github.io/owa-mail-mcp/agent-install.md
Пароль у меня не спрашивай — я введу его сам в окне настройки.
```

[Инструкция для агентов](docs/agent-install.md) описывает весь путь: проверка (`status --json`), установка без блокирующего окна (`OWA_MAIL_MCP_NO_SETUP=1`), подключение к клиенту (`connect`), окно настройки в фоне с заполненными адресом и почтой (`setup --server --email`), ожидание, проверка (`check`), перезапуск клиента и разбор ошибок. Пароль агент не видит и настройки безопасности за пользователя не меняет; если агент работает в облаке или песочнице, он отдаёт команды пользователю.

<details>
<summary>Другие способы установки</summary>

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install --python 3.12 git+https://github.com/Khomiakov7706/owa-mail-mcp
owa-mail-mcp setup
```

Если uv уже есть: `uv tool install --python 3.12 git+https://github.com/Khomiakov7706/owa-mail-mcp`.

pipx с Python 3.10+: `pipx install --python python3.12 git+https://github.com/Khomiakov7706/owa-mail-mcp`.

Ошибка `Could not find a version that satisfies the requirement mcp` означает, что установка шла системным Python 3.9: используйте скрипт выше или uv.
</details>

Окно настройки открывается в браузере, на языке системы (русский, English, 中文, Español; сменить — в правом верхнем углу окна). В нём три шага:

1. **Почтовый ящик Exchange.** Адрес веб-почты, почта, логин (`DOMAIN\login`, если вход Windows) и пароль, затем «Проверить подключение». При успехе видно ваше имя, число непрочитанных и последние письма. Если сервер недоступен, окно подскажет про VPN; если не подошёл пароль, так и скажет. Пароль сохраняется в системной связке ключей (Keychain, Credential Manager, Secret Service), а не в файле, и привязан к адресу сервера.
2. **Что разрешено ассистенту.** По умолчанию только чтение. Блок «Почта»: «Разрешить отправку писем» и «Разрешить наводить порядок в почте». Блок «Календарь»: «Показывать календарь ассистенту», «Разрешить создавать, переносить и отменять встречи» и способ подтверждения — в окне или в чате с агентом. Переключатели почты (черновики, флаги, категории, папки, «Удалённые» — без окна, всё обратимо). Каждое письмо и каждое изменение встречи подтверждаете вы; без окна уходят только письма, все получатели которых есть в списке «Получатели без подтверждения» (не больше 20 в час, только при разрешённой отправке).
3. **Подключение к ассистенту.** Кнопка «Добавить» для Claude Code, Codex, Claude Desktop, Cursor, OpenCode и Kilo Code, плюс готовые строки с кнопкой «Скопировать» для них и для VS Code.

### Конфиги клиентов вручную

В примерах замените `/Users/YOU` на свою домашнюю папку (точный путь показывает окно настройки).

| Клиент | Как подключить |
|---|---|
| Claude Code | `claude mcp add --scope user owa-mail -- ~/.local/bin/owa-mail-mcp` |
| Codex | `codex mcp add owa-mail -- ~/.local/bin/owa-mail-mcp` |
| Claude Desktop, Cursor | `{"mcpServers": {"owa-mail": {"command": "/Users/YOU/.local/bin/owa-mail-mcp"}}}` в `claude_desktop_config.json` / `~/.cursor/mcp.json` |
| OpenCode | `~/.config/opencode/opencode.json`, формат ниже |
| Kilo Code (новые версии) | `~/.config/kilo/kilo.jsonc`, тот же формат, что у OpenCode |
| Kilo Code (старые версии) | «Edit Global MCP» (`mcp_settings.json`) или `.kilocode/mcp.json`, формат `mcpServers` ниже |

OpenCode и новый Kilo Code не читают ключ `mcpServers`: у них ключ `mcp`, `"type": "local"` и команда массивом.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "owa-mail": {
      "type": "local",
      "command": ["/Users/YOU/.local/bin/owa-mail-mcp"],
      "enabled": true
    }
  }
}
```

Kilo Code, старые версии:

```json
{
  "mcpServers": {
    "owa-mail": {
      "command": "/Users/YOU/.local/bin/owa-mail-mcp",
      "args": [],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
```

Ниже — журнал: какие инструменты и когда вызывал ассистент, без содержимого писем.

<p align="center"><img src="docs/setup-light.png" alt="Окно настройки" width="520"></p>

**Сертификат, выпущенный внутри компании.** Если система не доверяет сертификату Exchange, проверка подключения покажет его: для кого и кем выдан, срок действия и отпечаток SHA-256. После «Доверять этому сертификату» сервер принимает именно этот сертификат (pinning) — проверку TLS для него никто не отключает. Если сертификат потом сменится, окно покажет старый и новый отпечатки: так плановую замену можно отличить от перехвата.

<p align="center"><img src="docs/setup-certificate.png" alt="Запрос доверия сертификату" width="520"></p>

**Если браузер открывает почту, а проверка пишет «не удаётся соединиться».** Проверка идёт к серверу тем же путём, что и вся программа: напрямую или через системный прокси (переменные `HTTPS_PROXY` и прокси из настроек macOS/Windows). Если сообщение называет конкретную причину, действуйте по ней:

- **DNS:** имя сервера не находится. Переподключите VPN.
- **Прокси:** указанный или системный прокси отказал в соединении.
- **TLS:** защищённое соединение не установилось.

Если браузер ходит через прокси, заданный PAC-скриптом (автоматическая настройка прокси), программа этот скрипт не читает. Окно подскажет, если в macOS включён PAC; адрес прокси тогда указывается в «Дополнительно» → «Прокси». Старые Exchange и шлюзы перед ними иногда работают только с устаревшими настройками TLS, которые браузеры принимают, а OpenSSL 3 нет. Окно распознает это и предложит разрешить их только для этого сервера; сертификат по-прежнему проверяется.

**Если ассистента подключили раньше, чем почту.** На первом же вызове MCP-сервер сам откроет окно настройки, а ассистент получит ответ «пользователь настраивает почту в открывшемся окне». Перезапускать клиент после настройки не нужно: сервер перечитывает настройки на лету, а новый пароль снимает блокировку, которую поставил отклонённый.

Попробовать без Exchange, на встроенном демо-ящике:

```bash
claude mcp add owa-mail-demo -e OWA_MAIL_BACKEND=demo -e OWA_MAIL_ALLOW_SEND=1 -- owa-mail-mcp serve
```

### Команды

| Команда | Что делает |
|---|---|
| `owa-mail-mcp` | В терминале открывает окно настройки (новый терминал после установки: скрипт добавляет `~/.local/bin` в PATH); запущенная MCP-клиентом работает как stdio-сервер |
| `owa-mail-mcp setup` | Окно настройки (`--no-browser` — только вывести адрес; `--server`, `--email`, `--username` — заполнить поля заранее) |
| `owa-mail-mcp serve` | MCP-сервер по stdio |
| `owa-mail-mcp status` | Версия, где лежат настройки, сохранён ли пароль (код 0 — настроено, 2 — нет; `--json` — для агентов) |
| `owa-mail-mcp connect <клиент>` | Подключить сервер к клиенту: `claude-code`, `codex`, `claude-desktop`, `cursor`, `opencode`, `kilo`; `--list` — какие найдены |
| `owa-mail-mcp check` | Проверить сохранённое подключение из терминала |
| `owa-mail-mcp diagnose` | Показать, что сервер отвечает на адресах EWS и OWA (коды, перенаправления, способы входа), без паролей и содержимого |

### Где лежат настройки и переменные окружения

Окно настройки пишет `config.json` (доступный только вашему пользователю) в `~/Library/Application Support/owa-mail-mcp` на macOS, `%APPDATA%\owa-mail-mcp` на Windows, `~/.config/owa-mail-mcp` на Linux. Там же хранится журнал вызовов. Переменные окружения переопределяют файл; это удобно для серверов без браузера и без связки ключей:

| Переменная | Что задаёт |
|---|---|
| `OWA_MAIL_SERVER`, `OWA_MAIL_EMAIL`, `OWA_MAIL_USERNAME`, `OWA_MAIL_PASSWORD` | Подключение без окна настройки |
| `OWA_MAIL_AUTH` | `ntlm` (по умолчанию), `basic`, `kerberos` |
| `OWA_MAIL_ALLOW_SEND` | `1` — разрешить отправку |
| `OWA_MAIL_CALENDAR` | `0` — скрыть календарь от ассистента целиком |
| `OWA_MAIL_ALLOW_CALENDAR` | `1` — разрешить создавать, переносить и отменять встречи |
| `OWA_MAIL_CALENDAR_CONFIRM` | `window` (по умолчанию) или `chat` — где подтверждать изменения встреч |
| `OWA_MAIL_ALLOW_ORGANIZE` | `1` — разрешить черновики, флаги, категории, папки и «Удалённые» |
| `OWA_MAIL_CONFIRM_TIMEOUT` | Сколько секунд ждать подтверждения (по умолчанию 50) |
| `OWA_MAIL_INTERNAL_DOMAINS` | Свои домены через запятую |
| `OWA_MAIL_OPEN_BROWSER` | `0` — не открывать браузер, а выводить адрес окна в stderr |
| `OWA_MAIL_BACKEND` | `demo` — встроенный демо-ящик |
| `OWA_MAIL_PROXY` | HTTPS-прокси до Exchange (`host:port`), если его нет в системных настройках |
| `OWA_MAIL_LANG` | Язык окон и сообщений: `ru`, `en`, `zh`, `es` (по умолчанию — язык системы или выбранный в окне настройки) |
| `OWA_MAIL_CONFIG_DIR` | Другая папка настроек |

## Инструменты

| Инструмент | Что делает |
|---|---|
| `get_status` | Кто пользователь (адрес, имя), текущее время, число непрочитанных, включена ли отправка |
| `check_mail` | Новые письма во «Входящих» (по умолчанию непрочитанные) с превью |
| `search_messages` | Поиск по тексту, отправителю, получателю, теме, датам (`7d`, `yesterday`, `2026-10-01`), вложениям, папкам |
| `get_message` | Полный текст письма (HTML переводится в текст), список вложений |
| `get_attachment` | Текст вложения: транскрипты и документы (.docx, .pdf, .txt, .vtt/.srt, .md, .csv, .html) и вложенные письма |
| `get_thread` | Вся переписка по письму, по порядку, без процитированной истории, со списком участников |
| `find_people` | Поиск в адресной книге организации (GAL) и контактах: имя, адрес, должность, отдел |
| `list_senders` | Кто писал за период: число писем, непрочитанные, последняя тема; для `sent` — кому писали вы |
| `send_email` | Новое письмо или ответ (`reply_to_message_id`, `reply_all`) **после подтверждения в окне**. С `format: "markdown"` — с форматированием: жирный, курсив, списки, заголовки, ссылки (то же у `forward_email` и `create_draft`) |
| `forward_email` | Переслать письмо вместе с вложениями **после подтверждения в окне** (или сразу, если все получатели в доверенном списке) |
| `create_draft` | Сохранить новое письмо, ответ или пересылку в «Черновики» — отправляете вы сами из Outlook или OWA |
| `list_folders` | Папки ящика: путь, число писем и непрочитанных |
| `update_messages` | Пометить прочитанным или непрочитанным, флаг (`flagged`, `complete`, `none`), добавить или убрать категории; до 100 писем за раз |
| `move_messages` | Переместить в папку (путь из `list_folders`), `archive`, `inbox`, `junk`; у перемещённого письма новый `message_id` |
| `delete_messages` | Перенести в «Удалённые»; навсегда не удаляет |
| `list_events` | Встречи в календаре за период: время, организатор, участники, `i_am_organizer`, повторяется ли; повторяющиеся встречи разложены на вхождения. Фильтры: текст или человек (`query`), ваш ответ (`response`: принято, под вопросом, без ответа, отклонено, свои), без отменённых, без событий на весь день |
| `get_current_and_next` | Что идёт сейчас и какая встреча следующая, через сколько минут |
| `find_events_with_person` | Встречи с человеком: ближайшие, прошедшие или те и другие |
| `get_event_details` | Встреча целиком: текст приглашения, каждый участник с ролью (обязательный / необязательный) и ответом, ссылка на подключение (Teams, Zoom, Телемост, Контур.Толк и др.) |
| `find_free_slots` | Свободное время для встречи: ваш календарь плюс занятость участников из Exchange (только «занят / свободен», без тем). Рабочие часы и дни настраиваются; для необязательных участников показано, кто свободен в каждом слоте; участники без данных о занятости (внешние) перечислены отдельно |
| `create_meeting` | Создать встречу (тема, время или длительность, участники, необязательные участники, место, повестка) и разослать приглашения; без участников — событие только в вашем календаре. Ссылку на Teams не создаёт. **После подтверждения**; в окне встречу можно поправить перед созданием |
| `cancel_meeting` | Своя встреча — отменить (участники получат уведомление, можно приложить сообщение); чужая — отклонить; событие без участников — удалить. Для повторяющейся — только это вхождение. **После подтверждения в окне** |
| `reschedule_meeting` | Перенести свою встречу или событие без участников; участники получат обновлённое приглашение. Чужую встречу перенести нельзя — агент предложит написать организатору. **После подтверждения в окне**; в окне можно выбрать другое время |

Промпты: `summarize_thread` (сводка переписки) и `triage_inbox` (разбор входящих: на что ответить, что для сведения).

Пример запроса к ассистенту: *«Что нового в почте со вчерашнего дня? Сделай сводку по треду про бюджет Q4 и подготовь ответ Анне, что оценку пришлю завтра»*. Ассистент вызовет `check_mail`, `get_thread`, затем `send_email`; в браузере откроется окно, где можно отправить письмо, отказаться или поправить текст и получателей.

## Как устроено подтверждение отправки

```
MCP-клиент ──stdio──► owa-mail-mcp ──EWS (HTTPS, NTLM)──► Exchange
                           │
                           └── http://127.0.0.1:<порт>/t/<секрет>/  ◄── браузер пользователя
```

1. `send_email` проверяет письмо: адреса только ASCII (кириллическая «е» в домене не пройдёт), запрещены управляющие символы направления текста (с ними `moc.live@ivan` выглядит как `ivan@evil.com`), лимит получателей, непустые тема и текст. Невидимые символы и скрытые копии выделяются предупреждением, внешние получатели — красным.
2. Письмо попадает в очередь (не больше трёх ожидающих), и сервер открывает в браузере локальную страницу. Её адрес содержит случайный секрет, который ассистент не видит.
3. Пока пользователь думает, вызов ждёт; клиентам, которые это поддерживают, раз в секунду отправляется progress.
4. **Отправить** — письмо уходит, ассистент получает `sent: true` и то, что реально отправлено. **Изменить** — пользователь правит получателей, тему и текст; уходит исправленная версия, ассистент получает `edited_by_user: true`. **Не отправлять** или истёкшее время — ассистент получает ошибку «ничего не отправлено, не повторяй без просьбы».
5. Повтор того же вызова в течение 10 минут возвращает первый результат (`duplicate: true`), а не второе письмо.
6. `forward_email` и изменения встреч (`create_meeting`, `cancel_meeting`, `reschedule_meeting`) идут через то же окно. Для пересылки окно показывает, чьё письмо пересылается и какие вложения уйдут; для встречи — участников, старое и новое время, текст для участников. Новую встречу можно **изменить** прямо в окне (тема, время, место, участники, текст), у переноса — выбрать другое время; правки проверяются так же, как запрос агента, а агент получает `edited_by_user: true` и то, что создано на самом деле.
7. Кнопка «Отправить» («Создать встречу», «Перенести» и т. п.) становится активной через 3 секунды после появления карточки, с обратным отсчётом: время прочитать, кому и что уходит, и защита от случайного щелчка. «Не отправлять» работает сразу.

**Подтверждение встреч в чате.** В блоке «Календарь» можно выбрать «В чате с агентом». Тогда вопрос «Создать встречу … ?» задаёт не модель, а само приложение агента через механизм MCP **elicitation**: сервер посылает клиенту запрос с формой (одна галочка «Подтверждаю»), клиент показывает её пользователю и возвращает ответ серверу. В истории окна такие изменения помечены «Подтверждено вами в чате». Работает в клиентах, которые поддерживают elicitation (Claude Code, Codex CLI, Cursor, VS Code, OpenCode); в остальных автоматически открывается окно подтверждения.

Может ли сервер убедиться, что подтверждение дал человек? Только настолько, насколько честен клиент. Если агент просто пишет «пользователь согласился», сервер это не учитывает: проверить слова модели нельзя. Поэтому сервер спрашивает сам, через клиента, и модель в этом обмене не участвует. Но форму показывает клиент, и спецификация разрешает клиенту отвечать на такие запросы автоматически. Если у вас в клиенте включено автоподтверждение всего подряд, это подтверждение ничего не стоит. Окно подтверждения от клиента не зависит: оно открывается в браузере по секретному адресу, который знает только браузер, поэтому по умолчанию используется оно.

**Доверенные получатели.** В окне настройки можно задать список адресов «Получатели без подтверждения». Письмо или пересылка, у которых **все** получатели (включая копии и скрытые копии) есть в списке, уходят сразу, без окна. Условия: отправка разрешена; в тексте нет невидимых символов; не больше 20 таких писем в час (дальше снова окно). Каждое такое письмо видно в истории окна с пометкой «Отправлено без подтверждения», а ассистент получает `confirmed: "trusted_recipients"`. Список меняется только в окне настройки. Добавляйте в него только тех, кому не страшно отправить что угодно из вашей почты: агентом можно манипулировать через текст входящих писем.

Ответ на кнопку приходит только из окна, никогда из MCP-клиента: модель можно уговорить чем угодно через текст письма, которое она только что прочитала. Окно слушает только loopback, не открывается во фрейме (`X-Frame-Options`, CSP `frame-ancestors 'none'`), принимает только JSON и проверяет `Host`/`Origin`, так что чужая веб-страница или DNS rebinding не нажмут кнопку за вас.

**Невидимые символы во встречах.** В теме, месте и тексте встречи сервер отклоняет невидимые символы (пробелы нулевой ширины, метки направления текста, управляющие символы), с помощью которых можно спрятать текст от проверки в окне. Похожие на пробел символы (неразрывный, узкий и т. п.) заменяются обычным пробелом. Эмодзи и письменности, которым нужны соединители (ZWJ/ZWNJ), не затрагиваются.

**Форматированные письма.** Агент никогда не передаёт HTML. Он пишет Markdown (`**жирный**`, `*курсив*`, списки, `[текст](https://…)`), а HTML собирает сервер: сначала экранирует весь текст, затем выпускает только `p`, `br`, `b`, `i`, `s`, `code`, заголовки, списки и ссылки `https`, `http`, `mailto`. Нет картинок, стилей, скриптов, форм и внешних ресурсов, поэтому письмо не может спрятать текст от проверки, отследить получателя или навредить ему. HTML-теги в тексте агента уходят как текст. Окно подтверждения показывает письмо так, как его увидит получатель, рядом с каждой ссылкой пишет её настоящий адрес и предупреждает, если текст ссылки похож на один сайт, а ведёт она на другой. Такое письмо не уходит доверенным получателям без окна.

**Пароль привязан к серверу.** В связке ключей пароль хранится под именем «логин@@сервер:порт». Если в настройках сменить адрес сервера, сохранённый пароль туда не уйдёт: окно попросит ввести пароль для нового сервера. Так подменённый адрес в `config.json` не выманит пароль на чужой сервер.

**Настройки подписаны.** `config.json` подписан ключом из связки ключей (HMAC-SHA256). Если файл изменили в обход окна настройки, важные разрешения (отправка, календарь, порядок в почте, доверенные получатели, лимиты, прокси, сертификаты) сбрасываются к безопасным значениям; окно настройки и `get_status` (`settings_reset: true`) об этом предупреждают, а повторное сохранение в окне снова подписывает файл. Это защищает от правки файла, но не от агента с полным shell: он может вызвать код программы сам.

**Граница защиты:** если у агента есть неограниченный shell от вашего пользователя, он может прочитать и пароль из keyring, и адрес окна. Подтверждение защищает от агента, которым манипулируют через содержимое писем, но не от агента, у которого уже есть полный доступ к машине.

## Другие меры защиты

- **Только чтение по умолчанию.** Отправка включается отдельным переключателем в окне настройки; до этого `send_email` отвечает, что отправка выключена.
- **Защита от блокировки учётной записи.** После первого отказа Exchange в пароле сервер перестаёт ходить в Exchange, пока пароль не введут заново в окне настройки, поэтому зациклившийся агент не заблокирует доменную учётку в AD. Есть и ограничение частоты: 120 запросов в минуту, не больше двух одновременно.
- **Содержимое писем — данные.** Инструкции сервера и описания инструментов прямо говорят модели не выполнять указания из писем.
- **stdout только для протокола.** Логи идут в stderr, в них нет тем, адресов и текстов писем.
- **Только HTTPS и pinning.** На `http://` пароль не отправляется; сертификату, которому не доверяет система, доверяют только явно и только по отпечатку.

## Чего программа не решает

Независимого аудита у программы ещё не было.

1. **Почта уходит AI-сервису.** Всё, что читает агент (тексты, вложения, транскрибации), отправляется компании, которая обслуживает агента. Для банка или другой регулируемой компании нужно согласие службы ИБ.
2. **Письма с «командами» для агента.** Просьба считать письма данными — не замок. Настоящая защита — окно подтверждения. Читать агент может всё; ограничить его папками пока нельзя.
3. **Способ установки.** `curl … | sh` ставит то, что сейчас в ветке main; подписанных релизов и фиксированных версий пока нет.
4. **Настройки, ослабляющие защиту** (выключены по умолчанию): устаревшие настройки TLS для сервера и пароль в `OWA_MAIL_PASSWORD` вместо связки ключей.
5. **Доступ к компьютеру.** Тот, кто уже вошёл под вашей учётной записью, может воспользоваться сохранённым паролем и запущенной программой.

Перед подключением рабочей почты убедитесь, что доверяете своей сети и провайдеру модели, с которой работает агент: ему уходят письма, которые агент читает.

## Почему EWS, а не OWA `service.svc`

OWA и EWS живут на одном сервере (`/owa` и `/EWS/Exchange.asmx`) и принимают одни и те же доменные учётные данные. Веб-клиент OWA ходит во внутренние JSON-вызовы (`/owa/service.svc?action=...` с токеном `X-OWA-CANARY`), но они не документированы. Для почты EWS удобнее: это документированный стабильный API, есть зрелая библиотека [exchangelib](https://github.com/ecederstrand/exchangelib), а у `service.svc` формат запросов меняется от версии к версии.

Если в вашей организации EWS закрыт, а OWA работает, бэкенд можно заменить: инструменты работают через интерфейс `MailBackend` (`src/owa_mail_mcp/backend.py`), и бэкенд на `service.svc` пишется отдельно, без изменений в инструментах и окне подтверждения.

Для Exchange Online (Microsoft 365) Microsoft отключает Basic auth и выводит EWS из эксплуатации; для облачной почты лучше взять сервер на Microsoft Graph (см. ниже).

## Готовые решения, которые стоит знать

Перед созданием проекта я посмотрел, что уже есть. Звёзды и активность проверяйте сами: доступ к поиску GitHub из этой среды был ограничен, часть данных взята из каталогов MCP-серверов.

| Проект | Протокол | Подходит для | Как с отправкой |
|---|---|---|---|
| [a-lagutov/outlook-ews-mcp](https://github.com/a-lagutov/outlook-ews-mcp), [viartemev/outlook-ews-mcp](https://github.com/viartemev/outlook-ews-mcp) | EWS (exchangelib), NTLM/Basic | On-prem Exchange: почта, календарь, контакты, вложения | Черновики + `send_draft`; подтверждение на стороне клиента |
| [ShermanGu/exchange-ews-mcp](https://glama.ai/mcp/servers/ShermanGu/exchange-ews-mcp) | EWS, NTLM, Windows | On-prem Exchange | Draft-first: письма создаются только как черновики |
| [askarzh/exchange-mcp](https://github.com/askarzh/exchange-mcp) | EWS + демон на Postgres | Архив и поиск по большому ящику | `SEND_ENABLED=false` по умолчанию |
| [azizmazrou/ews-mcp](https://github.com/azizmazrou/ews-mcp) | EWS | On-prem Exchange | Отправка выключена по умолчанию |
| [Softeria/ms-365-mcp-server](https://github.com/Softeria/ms-365-mcp-server) | Microsoft Graph | Microsoft 365 / Outlook.com | `send-mail` без отдельного подтверждения |
| [elyxlz/microsoft-mcp](https://github.com/elyxlz/microsoft-mcp) | Microsoft Graph | Microsoft 365, несколько аккаунтов | Без отдельного подтверждения |
| [tecnologicachile/mail-mcp](https://mcpservers.org/servers/tecnologicachile/mail-mcp) | IMAP/SMTP, Graph, EWS (OAuth) | Смешанные ящики | Запись включается переменными |
| [agimenez-dev/imap-mcp](https://glama.ai/mcp/servers/agimenezdev/imap-mcp) | IMAP/SMTP | Обычная почта | `mail_send` сначала возвращает превью, отправка с `confirm=true` |

Вывод: для on-prem Exchange уже есть рабочие серверы на exchangelib, и для простого чтения почты их достаточно. Но подтверждение отправки у них либо отсутствует, либо реализовано как «черновик + второй вызов» или `confirm=true`. И то и другое решает сама модель, а значит, его может обойти prompt injection. Этот проект добавляет то, чего не хватает: подтверждение, которое модель нажать не может, с выделением внешних получателей и возможностью править письмо, а также инструменты под конкретные задачи (треды без цитат, статистика отправителей, разбор входящих).

Ещё один путь — MCP elicitation (запрос подтверждения через UI самого клиента, спецификация 2025-06-18). Claude Code её поддерживает, Claude Desktop и многие другие клиенты нет, поэтому здесь используется собственное окно, которое работает с любым клиентом.

## Разработка

```bash
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
OWA_MAIL_BACKEND=demo OWA_MAIL_ALLOW_SEND=1 owa-mail-mcp -v   # stdio-сервер на демо-ящике
```

Тесты проходят полный цикл на демо-бэкенде: MCP-клиент → `send_email` → HTTP окна подтверждения → решение пользователя → отправка, а также отказ, тайм-аут, правки, дубликаты, проверки текста и защиту окна от чужих запросов. Окно настройки проверяется так же: проверка подключения, разбор ошибок, доверие сертификату и его смена, сохранение без пароля в файле, запись в конфиг Claude Desktop, подхват настроек работающим сервером. Pinning проверен на локальном HTTPS-сервере с самоподписанным сертификатом. EWS-бэкенд с живым Exchange не проверялся; первым шагом на реальном сервере нажмите «Проверить подключение».

```
src/owa_mail_mcp/
  server.py          инструменты, инструкции и промпты MCP, журнал вызовов
  runtime.py         текущие настройки и бэкенд, подхват изменений на лету, журнал
  setup.py           окно настройки: проверка подключения, сертификаты, установка в клиенты
  setup_page.html    страница окна настройки
  config.py          config.json и его подпись, переменные окружения, связка ключей
  tls.py             просмотр сертификата и pinning по отпечатку
  backend.py         интерфейс MailBackend
  ews_backend.py     Exchange через exchangelib
  demo_backend.py    демо-ящик в памяти
  confirm.py         очередь писем, ожидающих решения
  ui.py              окно подтверждения отправки
  confirm_page.html  страница окна подтверждения
  web.py             общая основа локальных окон (loopback, секретный адрес, CSP)
  safety.py          проверки исходящих писем, лимит запросов, блокировка после отказа в пароле
  text.py            HTML → текст, отрезание цитат, правила для текста, невидимые символы
  slots.py           поиск свободного времени для встречи
  formatting.py      Markdown → безопасный HTML для писем
```

## Лицензия

MIT