# Mail.ru MCP Connector

[English](README.en.md) · [Безопасность](SECURITY.md) · [Отправка](docs/SENDING.md)

Независимый self-hosted MCP-сервер для личного ящика Mail.ru. **Не официальный
продукт Mail.ru, VK или OpenAI; не связан с ними и не заявляет их одобрения.**
Этот репозиторий не является опубликованным приложением каталога ChatGPT и не
обещает попадание в каталог. Исходники доступны под [лицензией MIT](LICENSE).
В package.json оставлен private=true, чтобы исключить случайную публикацию в npm;
это не ограничивает самостоятельную установку из GitHub.

Каждый пользователь запускает свой экземпляр на собственном доверенном
компьютере или сервере. Владелец сам включает 2FA, создаёт отдельный пароль
приложения и вводит его только там. Разработчику не передаются пароль или ящик.
Выбранные письма получает MCP-клиент пользователя, например его AI-приложение.

## Возможности

| Инструмент | Действие |
| --- | --- |
| `list_folders` | Папки из административного списка; по умолчанию INBOX |
| `search_mail` | Поиск среди последних 500 писем папки, до 20 результатов |
| `read_mail` | Чтение по UID и UIDVALIDITY, без изменения Seen |
| `preview_reply` | При включённой отправке: проверить адрес ответа и цепочку |
| `send_mail` | При включённой отправке: одно текстовое письмо одному адресату |
| `reply_mail` | При включённой отправке: ответ по проверенным заголовкам |
| `send_status` | При включённой отправке: состояние попытки в локальном журнале |

**По умолчанию доступны только три инструмента чтения.** Нет удаления,
перемещения, IMAP APPEND, скачивания вложений, HTML-отправки, CC/BCC или reply-all.
Письма больше 2 МиБ не читаются; текст ответа ограничен 16 000 символов.
Метаданные вложений ограничены 30 записями. IMAP использует EXAMINE/BODY.PEEK;
TLS проверяется для фиксированных серверов Mail.ru. Поиск не охватывает всю историю.

## Требования и проверка без ящика

Node.js 24, npm; POSIX-система с приватными правами файлов. Отправка проверялась
на Linux/macOS, Windows для неё не поддерживается. Python 3 нужен только для
вспомогательных скриптов. Из распакованного checkout:

```sh
npm ci --ignore-scripts --no-audit --no-fund
npm run check
```

Тесты используют синтетические данные и поддельные транспорты, не Mail.ru.
Не добавляйте настоящий пароль в тесты или CI. SMTP-тест не является реальной
отправкой. Эта публичная копия не требует доступа к чьему-либо работающему сервису.

## Установка владельцем

1. Сохраните 2FA. В настройках Mail.ru создайте отдельный пароль внешнего
   приложения по [официальной инструкции](https://help.mail.ru/mail/login/mailer/).
   Основной пароль и одноразовые коды не подходят для этого подключения.
2. На **своём** сервере/компьютере создайте приватный каталог вне репозитория:

   ```sh
   install -d -m 700 "$HOME/.config/mailru-mcp"
   python3 scripts/store-app-password.py "$HOME/.config/mailru-mcp/app-password"
   ```

   Скрипт читает пароль скрыто в вашем терминале, создаёт файл 0600 и отказывается
   перезаписывать существующий. Не вставляйте пароль в команду, чат или git.
3. В окружении процесса задайте свой адрес и **путь**, не значение секрета:

   ```sh
   export MAILRU_USER='REPLACE_WITH_YOUR_MAILRU_ADDRESS'
   export MAILRU_PASSWORD_FILE="$HOME/.config/mailru-mcp/app-password"
   export MAILRU_FOLDERS_JSON='["INBOX"]'
   export MAILRU_SEND_ENABLED=false
   export MAILRU_ENABLE_HTTP=false
   npm start
   ```

   Замените placeholder реальным адресом локально. `.env.example` — справка;
   файлы `.env` автоматически не загружаются. `npm start` ожидает MCP на stdin/stdout,
   а не открывает страницу. Пароль Mail.ru может иметь более широкие права;
   ограничения чтением реализует код этого приложения.
4. Настройте в своём MCP-клиенте команду `node`, аргумент
   `/absolute/path/to/mailru-mcp-connector/src/index.js` и эти переменные.
   В [примере клиента](examples/mcp-client.json) все значения фиктивные.
   Только владелец должен иметь доступ к запуску и каналу stdio.

Для удалённого сервера нужен отдельно настроенный аутентифицированный личный
транспорт. Сам stdio не подключает сервер к веб-ChatGPT. Не выставляйте его
в интернет без авторизации и не давайте другим людям доступ к вашему процессу.
Туннели, OAuth и аккаунты эта установка автоматически не создаёт.

## Отправка и ответы

Перед включением прочитайте [правила отправки и отката](docs/SENDING.md).
Создайте постоянный приватный каталог отдельно от релиза и укажите его путь:

```sh
install -d -m 700 "$HOME/.local/state/mailru-mcp/send-state"
export MAILRU_SEND_STATE_DIR="$HOME/.local/state/mailru-mcp/send-state"
export MAILRU_SEND_ENABLED=true
```

Перезапустите MCP-процесс и обновите инструменты в своём клиенте. Требуйте
подтверждение адресата и текста перед каждой отправкой. Наличие write-аннотации
не заменяет проверку согласия клиентом. При отключении верните false и перезапустите.
Журнал не удалять. `submitted` — принятие SMTP, не доказательство доставки;
`unknown` требует сверки, а не повтора с новым ключом. Копия в «Отправленных»
кодом не создаётся. Подробности и ограничения в SENDING.md.

## Необязательный HTTP-режим

Экспериментальный HTTP-транспорт поддерживает **только чтение** и выключен
по умолчанию. Он требует собственного HTTPS reverse proxy и внешнего JWT/OIDC
провайдера с проверкой issuer/audience/subject владельца и scope mail:read.
Одновременный HTTP и SMTP запрещены при старте. [План самостоятельной установки](docs/DEPLOYMENT.md)
и шаблоны не являются готовой публичной службой. Общий multi-user сервер не поддержан.

## Данные и ограничения

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

Перед публикацией и изменением кода: [CONTRIBUTING.md](CONTRIBUTING.md).
Лицензии сторонних библиотек остаются у соответствующих правообладателей.