express-mcp

Неофициальный MCP-сервер для мессенджера eXpress и персональных агентов на macOS. Позволяет читать чаты и треды в группах, искать людей, отправлять сообщения и вложения, а также скачивать файлы с проверкой целостности. Авторизацией управляет постоянно работающий брокер сессии. Агенты подключаются к нему через локальный Unix socket и могут завершаться, не прерывая сессию.

Начало работы: Установка → Вход → Подключение к агентам.

Архитектура

• sessiond управляет взаимодействием с сервером и обновлением токенов. Системная блокировка не позволяет двум локальным брокерам одновременно владеть одной сессией.

• Токены, ключи, идентификатор устройства и номер поколения токенов хранятся вместе в отдельной записи macOS Keychain. Учётные данные официального приложения не читаются. Через MCP возвращаются содержимое чатов и диагностика без секретов.

• У каждого MCP-подключения свои короткоживущие подтверждения отправки и курсоры пагинации. При закрытии подключения они удаляются, но сессия брокера продолжает работать.

• Адреса серверов задаются явно и проверяются как HTTPS origins. При входе через QR адрес CTS должен точно совпасть с конфигурацией. HTTP-редиректы запрещены. Дополнительные корневые сертификаты можно подключить через NODE_EXTRA_CA_CERTS перед установкой.

Related MCP server: iMessage MCP Server

Установка на macOS

Нужны Node.js 22+, npm, активный вход пользователя в macOS с доступной связкой ключей login и Xcode Command Line Tools (xcode-select --install). Эта версия устанавливается из исходников и не опубликована в npm. Запуск брокера на Linux и Windows не поддерживается.

git clone https://github.com/artdaal/express-mcp.git
cd express-mcp
npm ci
npm run build

Создайте приватный JSON-файл конфигурации за пределами репозитория. У администратора вашей инсталляции нужно узнать точный CTS origin, адреса ETS и веб-клиента, а также идентификатор пакета клиента. Значения ниже приведены для примера — работающего сервиса по этим адресам нет:

{
  "ctsOrigin": "https://cts.chat.example.com",
  "etsOrigin": "https://ets.chat.example.com",
  "webOrigin": "https://chat.example.com",
  "appVersion": "3.66.47",
  "packageId": "com.example.express",
  "clientProfile": "express-cli-web"
}

node dist/src/cli.js configure < /absolute/private/deployment.json
node dist/src/cli.js install

configure сохраняет конфигурацию в ~/Library/Application Support/express-mcp/ с доступом только для владельца. install компилирует небольшие утилиты на Swift, устанавливает пользовательский LaunchAgent и проверяет готовность брокера. Перед заменой LaunchAgent создаётся приватная резервная копия для отката. Настройки агентских harness не меняются. Повторяйте install после изменения конфигурации или обновления исходников. Не перемещайте каталог установленного репозитория.

Вход

node dist/src/cli.js login
node dist/src/cli.js status
node dist/src/cli.js session-smoke

login открывает страницу с QR на том Mac, где работает брокер. Страница доступна только через loopback. Отсканируйте код официальным мобильным клиентом и подтвердите подключение устройства. В режиме совместимости на телефоне отображается Chrome 149.0, хотя браузерный движок для API-запросов не запускается. QR действует две минуты, а получить новый код на той же локальной странице можно в течение десяти минут.

status показывает локальное состояние. session-smoke проверяет авторизованный доступ: получает список чатов и читает одно недавнее сообщение, ничего не отправляя. Чтение может отметить чат прочитанным. Сам по себе authState:ready ещё не подтверждает работоспособность всей цепочки.

Подключайте каждый Mac отдельно. Не копируйте один ротируемый refresh token в два работающих брокера. При работе по SSH страница входа открывается на удалённом Mac. Для доступа к ней используйте доверенное удалённое подключение или локальный port forwarding; связка ключей пользователя на этом Mac должна быть доступна.

Подключение к агентам

Указывайте абсолютные пути и запускайте MCP от того же пользователя macOS, что и брокер. В примерах замените /absolute/express-mcp на путь к своему репозиторию. После изменения настроек перезапустите или обновите MCP-сессию в harness.

Codex

codex mcp add express -- /absolute/path/to/node /absolute/express-mcp/dist/src/cli.js serve

Эквивалентная запись в ~/.codex/config.toml:

[mcp_servers.express]
command = "/absolute/path/to/node"
args = ["/absolute/express-mcp/dist/src/cli.js", "serve"]

Подробнее — в документации по MCP в Codex. Попросите агента вызвать express_status, затем получить список чатов или прочитать знакомый чат.

Claude Code и другие MCP-клиенты

claude mcp add --transport stdio --scope user express -- /absolute/path/to/node /absolute/express-mcp/dist/src/cli.js serve

См. настройку MCP в Claude Code. Для других harness подойдёт стандартная конфигурация stdio:

{
  "mcpServers": {
    "express": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/express-mcp/dist/src/cli.js", "serve"]
    }
  }
}

OpenClaw: подключение по запросу

Установите скилл в workspace нужного агента:

node scripts/install-skill.mjs --workspace /absolute/openclaw/workspace

Установщик копирует каталог скилла и сохраняет локальные пути к исполняемым файлам. Глобальные MCP-инструменты не добавляются. По умолчанию агент видит только короткое описание скилла; полные инструкции загружаются, когда он выбирает его для задачи. Начните новую сессию и попросите, например: «Найди в eXpress чат проекта и кратко перескажи последние ответы». Механизм описан в документации OpenClaw.

Скилл вызывает CLI с JSON-вводом и ограниченным объёмом результата. Подготовка и отправка выполняются в одном MCP-подключении: подтверждение не теряется между отдельными запусками клиента. Пример ручной проверки без отправки сообщений:

node dist/src/cli.js agent <<'JSON'
{"operation":"search-chats","query":"Проект","limit":50,"pages":3}
JSON

Проверьте, что OpenClaw обнаружил скилл: openclaw skills --agent main info express-messenger --json. Вместо main укажите ID своего агента. Если каталог уже установлен, но gateway всё ещё возвращает старый список скиллов, выполните openclaw gateway restart и начните новую сессию агента.

Все примеры запросов находятся в инструкциях скилла. CLI не повторяет операции записи автоматически. confirmed:true означает, что вызывающая сторона подтверждает разрешение пользователя на конкретного получателя и содержимое; сам этот флаг не является отдельной системой контроля доступа. Перед обновлением скилла проверьте изменения и сохраните резервную копию: установщик не перезаписывает существующий каталог автоматически.

Возможности и ограничения

Для текста и вложений используются одноразовые подтверждения, привязанные к конкретному MCP-подключению и точному содержимому. Они действуют 120 секунд. На этапе подготовки вложения вычисляется хеш исходного файла; изменение файла делает подтверждение недействительным. Если результат загрузки или отправки неизвестен, автоматического повтора не будет. Изображение отправляется как зашифрованный PNG-оригинал с отдельно зашифрованным JPEG-превью. При скачивании проверяются подпись сообщения, целостность secretstream, размер и хеш расшифрованного файла. Результат сохраняется в новый приватный каталог.

Текущие ограничения: до 50 элементов на страницу MCP, до 20 страниц и примерно 200 KiB содержимого за один вызов CLI, до 10 MiB на вложение. Отправка в режиме изображения поддерживает только PNG. Список тредов ограничен недавними записями, глобального полнотекстового поиска нет. Некоторые старые сообщения могут не расшифровываться — для них возвращается явный признак ошибки. Интеграция неофициальная и зависит от версии протокола; настройки и политики разных инсталляций могут отличаться. Старый DOM-адаптер сохранён для регрессионных проверок, но для обычной установки рекомендуется брокер сессии.

Обслуживание

npm test
npm run typecheck
launchctl kickstart -k "gui/$(id -u)/io.github.express-mcp.express-sessiond"
# Восстановить LaunchAgent из резервной копии, созданной командой install:
node scripts/install.mjs --restore /absolute/private/backup-directory

Если Keychain заблокирован, потребуется действие пользователя на Mac. Отзыв сессии или неопределённый результат refresh требуют нового QR; повторные попытки сами по себе проблему не устранят. Для диагностики ошибок сервера смотрите этап запроса и код ошибки в status — без секретов. При неопределённом результате отправки сначала проверьте историю целевого чата. Если файл загрузился, а сообщение не создалось, на сервере может остаться зашифрованный файл без сообщения; автоматическая очистка таких файлов пока не реализована.

Разработка и источники

Тесты проверяют подписи QR-запросов, привязку к разрешённым origins, гонки и восстановление при refresh, изоляцию MCP-подключений, криптографию сообщений, шифрование и расшифровку файлов, ограничения CLI и установку пакета. Локальные материалы .agent/, учётные данные, браузерные профили, собранные бинарные файлы и тестовые данные не включаются в дистрибутив.

eXpress CLI от IH8E использовался как источник сведений о протоколе входа через QR в режиме совместимости с веб-клиентом. Он не является runtime-зависимостью, его исходный код здесь не распространяется. Тестовые примеры запросов содержат синтетические данные. Обработка refresh также учитывает консервативный подход из RFC 9700 §4.14.

Лицензия MIT. Проект не связан с разработчиком eXpress и не является официальным продуктом.