max-channel-mcp

MCP-сервер для публикации в каналы мессенджера MAX.

Подключается к Claude Desktop, Claude Code и другим клиентам, поддерживающим Model Context Protocol. После настройки ассистент может публиковать в вашем канале текст, фотографии, видео, аудио, документы и геометки — просто по вашей просьбе.

Вы:  Опубликуй в канале анонс с картинкой из ~/Downloads/banner.png
     и кнопкой на сайт.

ИИ:  [вызывает max_send_photos]
     Опубликовано. Ссылка: https://max.ru/ваш_канал/AaApSIDNYGM

Возможности

• Публикация текста с разметкой Markdown или HTML
• Альбомы до 10 фотографий, видео, смешанные альбомы
• Аудио, документы, геометки
• Кнопки под сообщениями — ссылки и callback
• Изменение и закрепление опубликованных сообщений
• Чтение истории канала

Удаление сообщений намеренно не реализовано: ассистент не должен иметь возможности стереть содержимое канала.

Требования

• Node.js 18.18 или новее
• Бот, созданный через MasterBot
• Права администратора у бота в вашем канале

Установка

Claude Code

claude mcp add max-channel \
  --scope local \
  --env MAX_BOT_TOKEN=ваш_токен \
  --env MAX_CHAT_ID=-10000000000001 \
  -- npx -y max-channel-mcp

Область local держит токен в вашем личном конфиге, а не в файле проекта.

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "max-channel": {
      "command": "npx",
      "args": ["-y", "max-channel-mcp"],
      "env": {
        "MAX_BOT_TOKEN": "ваш_токен",
        "MAX_CHAT_ID": "-10000000000001"
      }
    }
  }
}

Путь к файлу настроек:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Из исходников

git clone https://github.com/eduard256/max-channel-mcp.git
cd max-channel-mcp
npm install
npm run build

Затем укажите в конфиге node /полный/путь/dist/index.js вместо npx.

Настройка

Как получить токен

Откройте MasterBot, создайте бота по инструкции — в ответ придёт токен.

Как узнать идентификатор канала

1. Добавьте бота в канал администратором.
2. Выполните запрос:

curl -H "Authorization: ВАШ_ТОКЕН" https://platform-api2.max.ru/chats

3. Возьмите поле chat_id нужного канала. Обычно это отрицательное число.

Переменные окружения

Переменная	Обязательна	Назначение
MAX_BOT_TOKEN	да	Токен бота от MasterBot
MAX_CHAT_ID	да	Идентификатор канала для публикации
MAX_CA_CERT_PATH	нет	Свой корневой сертификат вместо встроенного
MAX_DISABLE_CUSTOM_CA	нет	1 — не подключать встроенный сертификат

Инструменты

Инструмент	Что делает
max_send_text	Текстовое сообщение
max_send_photos	От 1 до 10 фотографий с общей подписью
max_send_video	Одно или несколько видео
max_send_media_group	Фотографии и видео в одном сообщении
max_send_audio	Аудиофайл
max_send_file	Документ
max_send_location	Точка на карте
max_edit_message	Изменить текст опубликованного сообщения
max_pin_message	Закрепить сообщение
max_unpin_message	Снять закрепление
max_get_messages	Последние сообщения канала
max_get_channel_info	Сведения о канале и правах бота

Файлы передаются путями на диске. Кнопки — необязательный параметр кнопки у всех публикующих инструментов.

Ограничения MAX

Проверено на практике. В официальной документации эти правила описаны неполно.

Правило	Подробности
Длина текста	не более 4000 символов
Фотографии	до 10 в одном сообщении
Видео	несколько в одном сообщении допустимо
Аудио	ровно одно, ни с чем не сочетается
Документ	ровно один, ни с чем не сочетается
Геометка	ровно одна, ни с чем не сочетается
Фото + видео	единственное разрешённое сочетание разных типов
Кнопки	добавляются к любому сообщению
Разметка	работает только при явно указанном формате

Смешивание аудио, документов и геометок с другими вложениями сервер отклоняет с ошибкой вида Must be only one audio attachment in message.

Сертификаты

Серверы MAX используют сертификат удостоверяющего центра «Russian Trusted Root CA» (Минцифры РФ). Этого корня нет в стандартном хранилище Node.js, поэтому без дополнительной настройки соединение обрывается с ошибкой unable to get local issuer certificate.

Чтобы сервер работал на любой машине без ручной настройки, корневой сертификат включён в состав пакета — файл certs/russian_trusted_root.pem.

Как это устроено:

• сертификат применяется только к доменам max.ru, oneme.ru, okcdn.ru и mycdn.me — остальной трафик проверяется обычным образом;
• он добавляется к системным корням, а не заменяет их;
• при запуске сверяется контрольная сумма SHA-256; если файл подменён, сервер не стартует;
• ничего не устанавливается в систему — настройка действует только внутри процесса сервера.

Отпечаток встроенного сертификата:

d26d2d0231b7c39f92cc738512ba54103519e4405d68b5bd703e9788ca8ecf31

Сверить можно с опубликованным на gosuslugi.ru.

Если корень уже установлен в вашей системе, встроенный можно отключить: MAX_DISABLE_CUSTOM_CA=1. Свой сертификат подключается через MAX_CA_CERT_PATH.

Диагностика

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

Сообщение	Причина и решение
не задана переменная MAX_BOT_TOKEN	Проверьте env в конфиге клиента
Токен отклонён	Токен устарел или скопирован не полностью — перевыпустите через MasterBot
Нет доступа к каналу	Бот не добавлен в канал или не является администратором
Ошибка проверки сертификата	Убедитесь, что не задана MAX_DISABLE_CUSTOM_CA=1
Не удалось загрузить изображение	Проверьте путь и формат файла
Файл не найден	Указывайте абсолютные пути

Известная проблема библиотеки

Сервер использует официальную библиотеку @maxhub/max-bot-api. В версии 0.2.5 загрузка изображений и документов по пути к файлу или через поток не работает на Node.js 21 и новее: в FormData подставляется объект, который современный undici не распознаёт как файл, и сервер отвечает NO_IMAGE.

Этот сервер обходит проблему, читая файлы в память и передавая их как Buffer. Видео и аудио загружаются другим способом и не затронуты.

Лицензия

MIT