Skip to main content

Xonta MAX

MCP server for building bots and mini-apps for the MAX messenger (max.ru), in English and Russian. Free and open source.

Русская версия ниже

Why

MAX changed a lot in 2026: the API moved to platform-api2.max.ru behind the Минцифры root certificate, GET /chats was removed, adding members was restricted, webhooks became HTTPS-only, comments arrived. Language models still write the old API. This server gives an AI agent current facts and tools that check, generate and test MAX code, so the result works on the first try.

You don't need your own bot for most of it. Only the operator tools need a token.

Languages

Every answer comes in English or Russian. Each tool takes lang: "en" or lang: "ru", and agents pick the user's language on their own. The default is Russian; set XONTA_MAX_LANG=en to make it English. The official MAX docs are in Russian only, so this is also the easiest way to read them in English. Generated bots (max_scaffold_bot) come with comments, README and replies in the chosen language.

Tools

Tool What it does
max_api_reference Current Bot API and Mini Apps facts by topic or free-text search, each with a dev.max.ru link
max_endpoint_info One method: query, body, limits, gotchas, curl. Says when a method was removed
max_limits Every limit in one place: text, rate, keyboard, attachments, files, deep links, webhook
max_changelog Dated 2026 changes that break old code
max_lint_code Finds old host, token in query, Bearer, disabled TLS, removed methods, webhook mistakes, unsafe secret compare, wrong initData HMAC, Telegram leftovers. Line numbers and fixes
max_migrate_from_telegram Maps every Telegram API call in your code to MAX, lists what has no equivalent, gives a plan
max_scaffold_bot Ready bot in Python, TypeScript or Go: polling + webhook, certificate in Dockerfile, chat tracking, callbacks
max_build_message Message JSON with keyboard and images, validated, plus curl
max_validate_message Checks a body: 4000 chars, 210/30/7 keyboard, 3 per row for link/open_app, attachment combinations
max_split_text Splits long text into ≤4000-char messages at paragraph boundaries
max_convert_formatting Telegram MarkdownV2/HTML or LLM Markdown → MAX markup, reports what MAX can't show
max_deeplink ?start=, ?startapp=, mention, and a "Send to MAX" share link and button for any website, no bot needed
max_mock_update Realistic webhook updates for all 19 types, plus curl to your local endpoint
max_mock_init_data Correctly signed mini-app initData for backend tests
max_bridge_mock window.WebApp emulator to build mini-apps in a normal browser on localhost
max_check_webhook_secret Checks or generates a webhook secret
max_tracking_links Ads: a separate bot link (?start=), mini-app link, UTM link and promo code for every channel where you place an ad, plus a media plan CSV
max_ad_report Ads: CPM, cost per click or bot start, per lead and per order, ROAS, ROMI, with 95% intervals — says when a difference between channels may be chance
max_check_ad_post Ads: checks a post against Russian ad marking rules: the «Реклама» label, advertiser details, erid token, A+ mark for big channels
max_verify_signature Local only. Verifies initData, requestContact phone hash, request_contact vcf hash
max_bot_info, max_send_message, max_get_messages, max_get_chat, max_set_commands, max_webhook, max_get_updates, max_api_request Local only, with MAX_BOT_TOKEN. Act as your bot. Bodies are validated before sending, removed methods are refused

Connect

Hosted (no install)

https://mcp.xonta.ru/max/mcp
{
  "mcpServers": {
    "xonta-max": { "url": "https://mcp.xonta.ru/max/mcp" }
  }
}

The hosted server never accepts bot tokens: tools that need one are switched off there.

Local (stdio), with operator tools

{
  "mcpServers": {
    "xonta-max": {
      "command": "uvx",
      "args": ["xonta-max-mcp"],
      "env": {
        "MAX_BOT_TOKEN": "your token",
        "MAX_CA_FILE": "/path/to/russian_trusted_root_ca.pem",
        "XONTA_MAX_LANG": "en"
      }
    }
  }
}

Get the certificate at https://www.gosuslugi.ru/crt. Without MAX_BOT_TOKEN the server runs fine, just without the operator tools.

Try it

  • "Check this bot for MAX problems" + paste code
  • "Port my aiogram bot to MAX, what breaks?"
  • "Make a MAX bot in TypeScript with a webhook"
  • "Add a 'Send to MAX' button to my site's article pages"
  • "Give me a signed initData and a test for my FastAPI validator"
  • "I'm buying ads in 5 MAX channels for my shop's bot — make tracking links, then tell me which channel paid off"
  • "Where can I buy ads in MAX and what does it cost?"

Ads

The bot templates log every bot_started with a payload to starts.jsonl. Give each channel its own link from max_tracking_links, run the campaign, then pass the counts and orders to max_ad_report. Bot links work even when users never leave the messenger, which UTM-based analytics can't see. The server only calculates and checks text: it never touches ad accounts or budgets. max_check_ad_post is a hint, not legal advice.

Sources

Facts are checked against dev.max.ru, the official OpenAPI schema (github.com/max-messenger/api-schema) and the official Go and TypeScript clients. The official MAX agent skill (github.com/max-messenger/max-agents-skill, Apache-2.0) was used as a cross-check. Every answer says the date it is current for. If dev.max.ru says otherwise, dev.max.ru wins: open an issue and I'll update.

Creating a bot on MAX requires a verified profile on business.max.ru (organisation, sole proprietor, or since June 2026 self-employed). This server doesn't change that, it helps whoever builds the bot.

License

MIT


Xonta MAX — по-русски

MCP-сервер для разработки ботов и мини-приложений для мессенджера MAX (max.ru), на русском и английском. Бесплатный, с открытым кодом.

Зачем

В 2026 году MAX сильно поменялся: API переехал на platform-api2.max.ru с сертификатом Минцифры, GET /chats удалили, добавление участников ограничили, вебхуки теперь только по HTTPS, появились комментарии. Нейросети до сих пор пишут под старый API. Сервер даёт ИИ-агенту свежие факты и инструменты, которые проверяют, генерируют и тестируют код под MAX, чтобы всё заработало с первого раза.

Для большинства инструментов свой бот не нужен. Токен нужен только инструментам управления ботом.

Языки

Все ответы — на русском или английском. У каждого инструмента есть параметр lang: "ru" или lang: "en", агент сам выбирает язык пользователя. По умолчанию русский; XONTA_MAX_LANG=en делает английский языком по умолчанию. Официальная документация MAX есть только на русском, так что для иностранных разработчиков это ещё и способ прочитать её по-английски. Сгенерированные боты (max_scaffold_bot) получают комментарии, README и ответы на выбранном языке.

Инструменты

Инструмент Что делает
max_api_reference Актуальные факты по Bot API и мини-приложениям по теме или поиску, со ссылкой на dev.max.ru
max_endpoint_info Один метод: параметры, тело, лимиты, подводные камни, curl. Сообщает, если метод удалён
max_limits Все лимиты в одном месте: текст, частота запросов, кнопки, вложения, файлы, диплинки, вебхук
max_changelog Изменения 2026 года с датами, которые ломают старый код
max_lint_code Находит старый хост, токен в адресе, Bearer, отключённый TLS, удалённые методы, ошибки вебхука, небезопасное сравнение секрета, неверный HMAC для initData, остатки Telegram. С номерами строк и исправлениями
max_migrate_from_telegram Сопоставляет каждый вызов Telegram API в коде с MAX, перечисляет, чему нет аналога, даёт план
max_scaffold_bot Готовый бот на Python, TypeScript или Go: polling и вебхук, сертификат в Dockerfile, учёт чатов, кнопки
max_build_message JSON сообщения с кнопками и картинками, с проверкой и командой curl
max_validate_message Проверяет тело: 4000 символов, клавиатура 210/30/7, по 3 в ряду для link/open_app, сочетания вложений
max_split_text Режет длинный текст на сообщения до 4000 символов по абзацам
max_convert_formatting Telegram MarkdownV2/HTML или Markdown от нейросети → разметка MAX, сообщает, что MAX не покажет
max_deeplink ?start=, ?startapp=, упоминания и ссылка и кнопка «Отправить в MAX» для любого сайта, без бота
max_mock_update Правдоподобные события вебхука всех 19 типов и curl для отправки на ваш локальный адрес
max_mock_init_data Правильно подписанные initData для тестов бэкенда
max_bridge_mock Эмулятор window.WebApp, чтобы делать мини-приложение в обычном браузере на localhost
max_check_webhook_secret Проверяет или генерирует секрет вебхука
max_tracking_links Реклама: для каждого канала, где размещаете рекламу, своя ссылка на бота (?start=), мини-приложение, сайт с UTM и промокод, плюс медиаплан в CSV
max_ad_report Реклама: CPM, цена перехода или старта бота, заявки и заказа, ROAS, ROMI с 95%-интервалами — показывает, когда разница между каналами может быть случайной
max_check_ad_post Реклама: проверяет пост по правилам маркировки: пометка «Реклама», сведения о рекламодателе, токен erid, отметка A+ для больших каналов
max_verify_signature Только локально. Проверяет initData, хеш телефона из requestContact, хеш контакта от кнопки request_contact
max_bot_info, max_send_message, max_get_messages, max_get_chat, max_set_commands, max_webhook, max_get_updates, max_api_request Только локально, с MAX_BOT_TOKEN. Работают от имени вашего бота. Тело проверяется до отправки, удалённые методы не вызываются

Подключение

Готовый сервер (без установки)

https://mcp.xonta.ru/max/mcp
{
  "mcpServers": {
    "xonta-max": { "url": "https://mcp.xonta.ru/max/mcp" }
  }
}

Общий сервер не принимает токены ботов: инструменты, которым нужен токен, там выключены.

Локально (stdio), с управлением ботом

{
  "mcpServers": {
    "xonta-max": {
      "command": "uvx",
      "args": ["xonta-max-mcp"],
      "env": {
        "MAX_BOT_TOKEN": "ваш токен",
        "MAX_CA_FILE": "/путь/russian_trusted_root_ca.pem"
      }
    }
  }
}

Сертификат — на https://www.gosuslugi.ru/crt. Без MAX_BOT_TOKEN сервер работает, просто без инструментов управления ботом.

Что спросить

  • «Проверь этого бота на проблемы с MAX» + код
  • «Перенеси моего бота на aiogram в MAX, что сломается?»
  • «Сделай бота для MAX на TypeScript с вебхуком»
  • «Добавь кнопку „Отправить в MAX“ на страницы статей моего сайта»
  • «Дай подписанные initData и тест для моего валидатора на FastAPI»
  • «Покупаю рекламу в 5 каналах MAX для бота магазина — сделай ссылки для учёта, а потом скажи, какой канал окупился»
  • «Где купить рекламу в MAX и сколько это стоит?»

Реклама

Шаблоны ботов пишут каждый bot_started с payload в starts.jsonl. Дайте каждому каналу свою ссылку из max_tracking_links, проведите кампанию и передайте переходы и заказы в max_ad_report. Ссылки на бота считают даже тех, кто не выходил из мессенджера, — UTM-аналитика таких не видит. Сервер только считает и проверяет текст: к рекламным кабинетам и бюджетам он не обращается. max_check_ad_post — подсказка, а не юридическое заключение.

Источники

Факты сверены с dev.max.ru, официальной OpenAPI-схемой (github.com/max-messenger/api-schema) и официальными клиентами на Go и TypeScript. Для перекрёстной проверки использован официальный навык MAX для агентов (github.com/max-messenger/max-agents-skill, Apache-2.0). В каждом ответе указана дата актуальности. Если на dev.max.ru написано иначе, прав dev.max.ru: заведите issue, обновлю.

Создать бота в MAX можно только с подтверждённым профилем на business.max.ru (организация, ИП, с июня 2026 — самозанятый). Сервер этого не обходит, он помогает тому, кто делает бота.

Лицензия

MIT

Metadata

Release files for xonta-max-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xonta-max-mcp 0.1.0
File Size Uploaded Provenance Actions
xonta_max_mcp-0.1.0.tar.gz 91.8 kB Without provenance Details for xonta_max_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xonta-max-mcp 0.1.0
File Interpreter ABI Platform Actions
xonta_max_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for xonta_max_mcp-0.1.0-py3-none-any.whl

Total release size: 174.7 kB

Release files / xonta_max_mcp-0.1.0.tar.gz

Download URL xonta_max_mcp-0.1.0.tar.gz
Size 91.8 kB
Tags Source
SHA-256 checksum
How to use checksums
092e3aeed8c777d32aaaf58002d02c192c160f5e767c9b68c6f62db6e0719098
BLAKE2b-256 checksum
How to use checksums
754f85435b4141827132d28c9704f04d5bf6275d2f36ba5f07aac1a06891e900
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / xonta_max_mcp-0.1.0-py3-none-any.whl

Download URL xonta_max_mcp-0.1.0-py3-none-any.whl
Size 82.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b4ac9ce51ac39fa06a052edd5e25cdc8cf0fc475fb3f8d00dd09f0b5c84806a5
BLAKE2b-256 checksum
How to use checksums
f1233e4e13a394357e16fa5c2747f44de8678ac943ff1d46e9c57ed08aca3932
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for xonta-max-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page