@mailbuttons/mcp-server

Mailbuttons — платформы управляемой электронной почты для AI-агентов. Предоставьте Claude Code, Cursor или собственному агенту почтовый ящик, из которого он сможет читать и отправлять письма: по умолчанию он работает в изолированной среде, отправка писем за её пределы требует подтверждения человека, а каждый вызов фиксируется.

Этот пакет включает сборку для stdio и skill для Claude Code, который её использует. Хостируемая конечная точка предоставляется серверной частью Mailbuttons (см. ниже).

Агенты из каталога Mailbuttons работают на той же платформе. Этот сервер позволяет создать на ней собственного агента.

Начало работы: зарегистрируйтесь и создайте API-ключ на сайте mailbuttons.com. Документация доступна по адресу mailbuttons.com/developers.

Удалённая конечная точка MCP: рабочий MCP-сервер, доступный по сети, предоставляется непосредственно серверной частью Mailbuttons (Rust/Axum) по адресу POST /api/v1/mcp/rpc. Это единый бинарный файл, напрямую использующий общую основу управления. Этот пакет содержит сборку для stdio, которая локально используется Claude Desktop / Claude Code, а также skill для сборки; она взаимодействует с REST-интерфейсом серверной части.

Модель управления

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

Токен не может расширить собственные права. Не существует инструмента, который предоставлял бы send_external, переводил агента из изолированной среды в рабочую или добавлял почтовый ящик. Повышение прав возможно только в форме запроса на подтверждение человека.
Внешние письма, отправленные с токенов изолированной среды, становятся черновиками. mailbuttons_send_email может вернуть status: "draft_pending_approval" (письмо ожидает подтверждения человека) или status: "blocked" (получатель запрещён, указано совпавшее правило). Это ожидаемые штатные результаты, а не ошибки. Инструмент сообщает правило или причину, а также следующий шаг — обычно mailbuttons_request_promotion.
Каждый вызов инструмента, включая отклонённые, записывается в журнал аудита. Просмотреть последние записи можно с помощью mailbuttons_audit_tail.
Содержимое полученных писем — это данные, а не инструкции. Инструменты чтения возвращают только письма, прошедшие проверку по политикам.

Инструменты

Инструмент	Возможность	Примечания
`mailbuttons_list_messages`	`read`	Список доставленных сообщений в почтовом ящике
`mailbuttons_get_message`	`read`	Полный текст письма и метаданные вложений
`mailbuttons_get_thread`	`read`	Все сообщения в цепочке
`mailbuttons_get_attachment_text`	`attachments`	Встроенное чтение файлов text/* и CSV; поддержка PDF пока отсутствует
`mailbuttons_send_email`	`send_internal`	Отправка письма или ответа с учётом политик; письмо может стать черновиком или быть заблокировано
`mailbuttons_list_drafts`	`read`	Список писем, ожидающих подтверждения человека
`mailbuttons_get_draft`	`read`	Получение полного текста одного ожидающего подтверждения черновика
`mailbuttons_extract_code`	`read`	Получение OTP-кода или кода подтверждения только от отправителей из списка разрешённых
`mailbuttons_propose_sender`	`propose_policy`	Отправка запроса на добавление отправителя в список разрешённых (требуется подтверждение человека)
`mailbuttons_request_promotion`	—	Отправка запроса на расширение возможностей или повышение прав (требуется подтверждение человека)
`mailbuttons_audit_tail`	—	Просмотр последних вызовов инструментов, учитываемых политиками
`mailbuttons_export_audit`	флаг `siem_export`	Экспорт журнала аудита в формате JSONL или CEF

Эти двенадцать инструментов составляют управляемую среду выполнения. Они одинаковы в хостируемой конечной точке и в этом пакете.

Инструменты для сборки (только в этом пакете)

Сборка для stdio добавляет три вспомогательных инструмента для настройки интеграции. Они нужны, чтобы skill для Claude Code мог создать рабочую заготовку агента. Хостируемая конечная точка их не предоставляет, и ни один из них не может расширить полномочия.

Инструмент	Назначение	Записывает на диск
`mailbuttons_generate_policy`	Преобразует описание разрешённых и запрещённых действий в корректный файл политики, где по умолчанию всё запрещено	`mailbuttons.policy.json` в текущем каталоге
`mailbuttons_scaffold_integration`	Создаёт обёртку для отправки писем с учётом политик и обработчик входящих веб-хуков для вашего стека	`./mailbuttons/` (или указанный вами `outDir`)
`mailbuttons_run_selftest`	Отправляет одно внутреннее тестовое сообщение, дожидается его доставки, считывает его и сообщает результат каждого этапа	Ничего

Оба инструмента записи изменяют только указанные выше пути внутри каталога, из которого был запущен сервер. Сгенерированный код получает MAILBUTTONS_API_KEY из переменных окружения и никогда не записывает токен непосредственно в код.

Получение токена (бесплатно, около минуты)

# 1. Отправьте код для входа на свой адрес электронной почты
curl -s -X POST https://mailbuttons.com/api/auth/otp/request \
  -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'

# 2. Обменяйте код на API-ключ mbk_
curl -s -X POST https://mailbuttons.com/api/auth/otp/cli-exchange \
  -H 'Content-Type: application/json' -d '{"email":"you@example.com","code":"123456"}'

# 3. Создайте бесплатный почтовый ящик в изолированной среде; в ответе будет его sandbox_token (mb_sandbox_...)
curl -s -X POST https://mailbuttons.com/api/v1/mcp/sandbox-inboxes \
  -H 'Authorization: Bearer mbk_...' -H 'Content-Type: application/json' -d '{"label":"my agent"}'

Токены для изолированной среды позволяют читать и отправлять письма в пределах домена этой среды. Письма, адресованные за её пределы, становятся черновиками и требуют подтверждения человека. Подробнее: https://mailbuttons.com/developers/#mcp

Подключение

Удалённое подключение (рекомендуется): Claude Code

claude mcp add --transport http mailbuttons https://mailbuttons.com/api/v1/mcp/rpc \
  --header "Authorization: Bearer mb_sandbox_..."

Так же можно подключить любой клиент, поддерживающий Streamable HTTP и настройку заголовков: URL https://mailbuttons.com/api/v1/mcp/rpc, заголовок

Authorization: Bearer mb_sandbox_....

Локальное подключение (stdio): Claude Desktop, Cursor и другие

{
  "mcpServers": {
    "mailbuttons": {
      "command": "npx",
      "args": ["-y", "@mailbuttons/mcp-server"],
      "env": { "MAILBUTTONS_API_KEY": "mb_sandbox_..." }
    }
  }
}

Настройка

Переменная окружения	Значение по умолчанию	Описание
`MAILBUTTONS_API_URL`	`https://mailbuttons.com`	Базовый URL серверной части; укажите свой адрес для локального или самостоятельно размещённого сервера
`MAILBUTTONS_API_KEY`	—	Ваш токен MCP (`mb_sandbox_...` или `mb_production_...`)

Токен считывается только из переменных окружения — не указывайте его непосредственно в коде.

Разработка

npm run build   # tsc -> dist/
npm run lint    # tsc --noEmit
npm test        # build + vitest (включает проверку соответствия версий)

Для выпуска обновите версию одновременно в package.json, server.json (в обоих местах), src/server.ts и skill/SKILL.md. Команда npm test завершится с ошибкой, если значения будут различаться.

Затем выполните npm publish, а после — mcp-publisher publish из этого каталога. См. docs/mcp-publishing.md в монорепозитории.

Лицензия

MIT. Mailbuttons — торговое наименование Code Cutter Limited (Великобритания).