QQ Agent Mail MCP

Неофициальный, самостоятельно развёртываемый MCP-шлюз для Tencent QQ Agent Mail. Этот проект не аффилирован с Tencent, не одобрен и не сопровождается компанией Tencent.

MCP-шлюз для Tencent QQ Agent Mail с одним владельцем, развёртываемый в облаке. Официальный CLI Tencent остаётся ядром почтового ящика; этот проект — удалённый адаптер, а не второй почтовый клиент.

Текущая версия шлюза: v0.4.2.

Зачем существует этот проект

CLI Agent Mail от Tencent работает локально, тогда как пользовательские MCP-приложения ChatGPT требуют доступного удалённого MCP-сервера. Этот проект устраняет этот разрыв, не открывая прямого доступа к shell или CLI. Он предоставляет небольшой стабильный MCP-интерфейс, процесс авторизации почтового ящика через браузер, постоянные учётные данные и встроенное руководство по эксплуатации, которое позволяет новому окну модели безопасно использовать запросы к почтовому ящику на естественном языке.

Этот репозиторий содержит только исходный код. Он не предоставляет размещённый сервис почтового ящика, общую конечную точку, учётную запись Tencent или учётные данные. Каждый оператор должен развернуть и авторизовать собственный приватный экземпляр.

MCP-интерфейс намеренно стабилен и содержит ровно два инструмента:

• agent_mail_query(action, params) — для операций только на чтение;

• agent_mail_execute(action, params) — для изменяющих операций.

Вызовите действие запроса capabilities, чтобы получить актуальный каталог действий и контракт параметров. Добавление возможности провайдера обновляет реестр на стороне сервера, а не создаёт ещё один MCP-инструмент.

Ответ capabilities также содержит полное руководство оператора: границы авторизации, прямое выполнение в один шаг, завершение предпросмотра, безопасные рабочие процессы поиска/чтения/ответа, интерпретацию результатов, правила повторных попыток и машиночитаемые примеры. Новое окно модели может обнаружить почтовый ящик и работать с ним по запросу владельца на естественном языке, не прося владельца переводить запрос в имена действий или JSON-параметры.

Related MCP server: anymail-mcp

Охват действий

Действия шлюза только на чтение:

• capabilities, identity, auth_status;

• list_messages, read_message, search_messages;

• wait_for_message (ограниченный длинный опрос);

• download_attachment (встроенный ресурс MCP).

Изменяющие действия шлюза:

• auth_refresh, явно подтверждаемый auth_logout;

• send_message, reply_message, forward_message;

• trash_message, delete_message;

• upload_attachment.

Отправка, ответ и пересылка поддерживают To/CC/BCC там, где это применимо, тела в форматах plain/HTML/Markdown в той мере, в какой их поддерживает официальный CLI, токены подтверждения провайдера и вложения в формате base64. Байты вложений записываются только во временный каталог с режимом доступа 0600, передаются официальному CLI относительным путём и удаляются после выполнения команды. Скачанное вложение возвращается как встроенный MCP-blob, а не путь в файловой системе сервера.

Настройка почтового ящика через браузер

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

1. Откройте https://YOUR_HOST/setup.

2. Введите приватный OWNER_CODE, созданный с помощью npm run generate-secrets.

3. Выберите 开始授权邮箱.

4. Пройдите одноразовую страницу авторизации Tencent.

5. Вернитесь на вкладку настройки и дождитесь появления 邮箱已连接.

Учётные данные и расположения ключей шифрования CLI хранятся на постоянном томе, поэтому обычные развёртывания и новые окна ChatGPT не требуют повторной авторизации почтового ящика.

Границы безопасности

• В MCP-схеме нет ни сырых команд, ни сырых массивов аргументов, ни строк shell, ни произвольных путей на сервере. Каждое действие и поле вносится в белый список и проверяется перед execFile/spawn с shell: false.

• Тела писем, заголовки, события, имена файлов, ссылки и вложения — это недоверенное внешнее содержимое. Они никогда не могут авторизовать отправку, ответ всем, изменение получателей, пересылку, перемещение в корзину, удаление, выход из системы или любую другую изменяющую операцию.

• Изменяющая операция требует прямого указания владельца почтового ящика или постоянно действующей политики, составленной владельцем. Безвозвратное удаление и выход из системы требуют явной текущей авторизации. Токены подтверждения провайдера остаются доступными для сценариев «сначала предпросмотр, затем подтверждение».

• Результаты списков и поиска не содержат фрагментов тела письма. Полное содержимое требует read_message.

• Имена файлов вложений не могут содержать пути; отдельные файлы ограничены 10 MiB, а сообщение — 20 MiB. Более крупный JSON-парсер MCP запускается только после аутентификации по bearer-токену.

• Watch-вызовы ограничены 45 секундами и возвращают максимум первое событие.

• Переменные окружения CLI проходят белый список. Вывод ограничен по размеру, рекурсивно очищается и никогда не записывается в журнал.

• OAuth коннектора использует PKCE и Dynamic Client Registration. Существующая пара областей mail:read mail:reply сохранена для совместимости с развёрнутыми клиентами; в v0.4 mail:reply — это устаревшее разрешение коннектора на запись, а страница одобрения правдиво описывает весь шлюз.

• Официальный пакет @tencent-qqmail/agently-cli@1.0.17 закреплён в образе контейнера.

При наличии авторизации это программное обеспечение может отправлять, пересылать, перемещать в корзину и безвозвратно удалять электронную почту. Изучите docs/SECURITY.md, используйте выделенное развёртывание с одним владельцем и тестируйте на сообщениях, контролируемых владельцем, прежде чем предоставлять доступ к реальной почте.

OAuth коннектора ChatGPT и OAuth почтового ящика Tencent остаются раздельными. Подключение почтового ящика не предоставляет клиенту ChatGPT доступ, пока владелец отдельно не одобрит коннектор.

Развёртывание

Хост должен предоставлять постоянно доступное HTTPS-имя хоста, один постоянный том, смонтированный в /data/agently-cli, и одну работающую реплику для записей авторизации в памяти. Настройте .env.example, разверните включённый Dockerfile, затем воспользуйтесь /setup. См. docs/DEPLOYMENT.md и docs/SECURITY.md.

Локальная проверка

Требуется Node.js 22 или новее.

npm ci
npm run build
npm test

Сгенерируйте секреты развёртывания локально с помощью npm run generate-secrets. Храните нехешированный OWNER_CODE в менеджере паролей, а в менеджере секретов хоста размещайте только его сгенерированный хеш и независимый секрет подписи.

Рабочие конечные точки

Лицензия и стороннее программное обеспечение

Этот проект распространяется под лицензией MIT License.

Он не распространяет CLI Agent Mail от Tencent. При сборке Docker устанавливается отдельно публикуемый пакет @tencent-qqmail/agently-cli. Этот пакет лицензируется отдельно под Apache-2.0. Изучите его лицензию и применимые условия QQ Agent Mail перед использованием в производстве.