xonta-max-mcp
Provides tools for building, validating, and testing bots and mini-apps for the MAX messenger (max.ru), including Bot API reference, endpoint details, limits, code linting and migration, bot scaffolding, message building and validation, deep links, webhook/update and initData mocks, tracking links, ad reporting, and local bot operator tools.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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.
Related MCP server: mcp-max-messenger
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 |
| Current Bot API and Mini Apps facts by topic or free-text search, each with a dev.max.ru link |
| One method: query, body, limits, gotchas, curl. Says when a method was removed |
| Every limit in one place: text, rate, keyboard, attachments, files, deep links, webhook |
| Dated 2026 changes that break old code |
| Finds old host, token in query, |
| Maps every Telegram API call in your code to MAX, lists what has no equivalent, gives a plan |
| Ready bot in Python, TypeScript or Go: polling + webhook, certificate in Dockerfile, chat tracking, callbacks |
| Message JSON with keyboard and images, validated, plus curl |
| Checks a body: 4000 chars, 210/30/7 keyboard, 3 per row for link/open_app, attachment combinations |
| Splits long text into ≤4000-char messages at paragraph boundaries |
| Telegram MarkdownV2/HTML or LLM Markdown → MAX markup, reports what MAX can't show |
|
|
| Realistic webhook updates for all 19 types, plus curl to your local endpoint |
| Correctly signed mini-app initData for backend tests |
|
|
| Checks or generates a webhook secret |
| Ads: a separate bot link ( |
| 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 |
| Ads: checks a post against Russian ad marking rules: the «Реклама» label, advertiser details, erid token, A+ mark for big channels |
| Local only. Verifies initData, requestContact phone hash, request_contact vcf hash |
| Local only, with |
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 и ответы на выбранном языке.
Инструменты
Инструмент | Что делает |
| Актуальные факты по Bot API и мини-приложениям по теме или поиску, со ссылкой на dev.max.ru |
| Один метод: параметры, тело, лимиты, подводные камни, curl. Сообщает, если метод удалён |
| Все лимиты в одном месте: текст, частота запросов, кнопки, вложения, файлы, диплинки, вебхук |
| Изменения 2026 года с датами, которые ломают старый код |
| Находит старый хост, токен в адресе, |
| Сопоставляет каждый вызов Telegram API в коде с MAX, перечисляет, чему нет аналога, даёт план |
| Готовый бот на Python, TypeScript или Go: polling и вебхук, сертификат в Dockerfile, учёт чатов, кнопки |
| JSON сообщения с кнопками и картинками, с проверкой и командой curl |
| Проверяет тело: 4000 символов, клавиатура 210/30/7, по 3 в ряду для link/open_app, сочетания вложений |
| Режет длинный текст на сообщения до 4000 символов по абзацам |
| Telegram MarkdownV2/HTML или Markdown от нейросети → разметка MAX, сообщает, что MAX не покажет |
|
|
| Правдоподобные события вебхука всех 19 типов и curl для отправки на ваш локальный адрес |
| Правильно подписанные initData для тестов бэкенда |
| Эмулятор |
| Проверяет или генерирует секрет вебхука |
| Реклама: для каждого канала, где размещаете рекламу, своя ссылка на бота ( |
| Реклама: CPM, цена перехода или старта бота, заявки и заказа, ROAS, ROMI с 95%-интервалами — показывает, когда разница между каналами может быть случайной |
| Реклама: проверяет пост по правилам маркировки: пометка «Реклама», сведения о рекламодателе, токен erid, отметка A+ для больших каналов |
| Только локально. Проверяет initData, хеш телефона из requestContact, хеш контакта от кнопки request_contact |
| Только локально, с |
Подключение
Готовый сервер (без установки)
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
Available Tools
21 toolsmax_ad_reportARead-onlyIdempotentInspect
Compare ad placements in MAX by real results: CPM, cost per click or bot start, cost per lead and per order, ROAS, profit after ads and ROMI (with margin), conversion with a 95% confidence interval. Says when a difference between channels may be chance and when there is too little data. A calculator only: it does not touch ad accounts or move money.
Inputs: placements (required), lang, events, campaign, +1 more.
max_api_referenceARead-onlyIdempotentInspect
Look up current facts about the MAX Bot API and Mini Apps (MAX Bridge) with links to dev.max.ru.
Covers base URL and auth, the Russian Trusted Root CA, advertising in MAX (topic 'ads'), webhooks vs long polling, sending messages, inline keyboards and callbacks, formatting, uploads, chat tracking without GET /chats, mini-apps, initData validation, deep links, who may create bots, official libraries. Language models usually know an outdated API (platform-api.max.ru, token in query, GET /chats) — use this before writing MAX code. With no arguments returns the list of topics.
Inputs: lang, query, topic.
max_bridge_mockARead-onlyInspect
Generate max-bridge-mock.js: a window.WebApp emulator to develop MAX mini-apps in a normal browser on localhost.
Emulates initData/initDataUnsafe (signed if a test token is given), BackButton (Esc), DeviceStorage and SecureStorage (localStorage, 10-key cap), BiometricManager, HapticFeedback, NfcManager, ScreenCapture, requestContact with a valid hash, openLink/downloadFile/shareMaxContent click requirements and per-platform restrictions. Logs every call. Use only on localhost.
Inputs: lang, phone, user_id, platform, +4 more.
max_build_messageARead-onlyIdempotentInspect
Build a correct POST /messages request for MAX: JSON body with inline keyboard and images, validation result and a ready curl command. Use it instead of hand-writing keyboard JSON.
Inputs: lang, text, format, buttons, +5 more.
max_changelogBRead-onlyIdempotentInspect
Dated MAX platform changes in 2026 that break old code: host move to platform-api2, removed GET /chats, restricted member adding, HTTPS-only webhooks, comments API, self-employed access.
Inputs: lang.
max_check_ad_postARead-onlyIdempotentInspect
Check an ad post for MAX against Russian ad marking rules: the 'Реклама' label at the top, advertiser details (name and INN/OGRN or a site), an erid token in the link or text, the A+ mark for channels over 10,000 subscribers, and the 4000-character limit. A hint, not legal advice; ORD registration is not checked.
Inputs: text (required), lang, links, advertiser_site, +2 more.
max_check_webhook_secretARead-onlyIdempotentInspect
Check a MAX webhook secret against the rules (5-256 chars, A-Z a-z 0-9 _ -) or generate a strong one.
Inputs: lang, secret.
max_convert_formattingARead-onlyIdempotentInspect
Convert formatted text to MAX markup: Telegram MarkdownV2 (underline x → ++x++, unescape), Telegram HTML (tg://user → max://user, spoilers dropped) or ordinary Markdown from an LLM (lists → bullets, rules removed). Reports what MAX cannot show (spoilers, tables, lists, inline images). Use the returned format value in the body.
Inputs: text (required), source (required), lang, target.
max_deeplinkARead-onlyIdempotentInspect
Build and validate MAX deep links. 'share' gives a link, an HTML button and a JS helper that open MAX's chat picker with prefilled text — works on any website or AI agent output without owning a bot. Payload limits are checked, because MAX silently drops payloads that are too long or have bad characters.
Inputs: kind (required), lang, text, payload, +3 more.
max_endpoint_infoARead-onlyIdempotentInspect
Details of one MAX Bot API method (query params, body, limits, gotchas, docs link) or the full method list.
Also tells when a method was removed or restricted (GET /chats, POST /chats/{chatId}/members).
Inputs: lang, path, verb.
max_limitsARead-onlyIdempotentInspect
All MAX platform limits in one table: text length, rate limits, keyboard size, attachments, file sizes, deep link payloads, webhook rules, bots per profile — each with a source link. Also update types, button types, errors.
Inputs: lang.
max_lint_codeARead-onlyIdempotentInspect
Check MAX bot or mini-app code for known mistakes, with line numbers and fixes.
Finds: old host platform-api.max.ru, token in query string, 'Bearer' prefix, disabled TLS verification, removed GET /chats, restricted member adding, type=photo uploads, wrong webhook setup (port, HTTP, /webhook), disable_link_preview in body, plain == comparison of the webhook secret, initData signed directly with the token, trusting initDataUnsafe, hardcoded upload hosts, Telegram leftovers. Static, never runs the code.
Inputs: code (required), lang.
max_migrate_from_telegramARead-onlyIdempotentInspect
Plan a port of a Telegram bot or Web App to MAX.
With code: every Telegram API usage with line number and the MAX replacement, features with no MAX equivalent, effort estimate and a step-by-step plan. Without code: the full Telegram → MAX method map.
Inputs: code, lang.
max_mock_init_dataARead-onlyInspect
Produce a correctly signed MAX mini-app initData string (two-step HMAC with 'WebAppData') for backend tests, with the token used, so you can check your validator end to end.
Inputs: lang, user_id, chat_type, first_name, +3 more.
max_mock_updateARead-onlyInspect
Generate a realistic MAX webhook Update for tests, shaped like the official schema, plus a curl command to send it to your local webhook. Lets you test a bot before it passes moderation or without a token.
Inputs: update_type (required), lang, text, secret, +5 more.
max_scaffold_botARead-onlyInspect
Generate a ready MAX bot project: polling for dev, webhook for prod, the Russian Trusted Root CA in the Dockerfile, chat tracking without GET /chats, callback answers, constant-time secret check, rate limits and text splitting (Python). lang sets the language of comments, README and the bot's replies.
Returns a map of file name → content. Write the files as they are. Creating the bot itself and getting a token requires a verified profile on business.max.ru.
Inputs: lang, language.
max_split_textBRead-onlyIdempotentInspect
Split text into MAX messages of at most 4000 characters, cutting at paragraphs, lines or sentences.
Inputs: text (required), lang, limit.
max_tracking_linksARead-onlyIdempotentInspect
Make a separate tracking link (and promo code) for every channel where an ad is placed in MAX, so you can see which placement brought users and sales. Bot links use ?start=: the id arrives in bot_started.payload, which works even for clicks that never leave the messenger. Returns a media plan as CSV. Then feed the counts to max_ad_report.
Inputs: campaign (required), placements (required), lang, bot_name, +4 more.
max_validate_messageARead-onlyIdempotentInspect
Validate a message body before sending to MAX: 4000-char text, format, keyboard limits (210/30/7, 3 per row with link/open_app/request_*), button fields and lengths, attachment combinations (≤12 media, file only with a keyboard, audio/sticker/contact alone), comment restrictions, Telegram fields left in the body.
Inputs: body (required), lang, target, chat_type.
max_verify_signatureARead-onlyIdempotentInspect
Verify a MAX signature locally: mini-app initData (two-step HMAC), requestContact phone hash, or the hash of a contact shared through a request_contact button. Explains why a check failed (wrong formula, double decoding, stale auth_date). Available only when the server runs on your machine.
Inputs: kind (required), hash, lang, phone, +6 more.
server_statusBRead-onlyIdempotentInspect
Server version, facts date, mode (hosted or local), languages and whether operator tools are active.
Inputs: lang.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Tools cluster into clearly recognizable roles: reference lookups (max_api_reference, max_endpoint_info, max_limits, max_changelog), code assistance (max_lint_code, max_migrate_from_telegram, max_convert_formatting), message composition (max_validate_message, max_build_message), test fixtures (max_mock_update, max_mock_init_data, max_bridge_mock) and ads tooling. The main fuzziness is validate vs. build (build also returns a validation result) and the four reference tools, whose boundaries an agent must read carefully to pick correctly. Overall still well-separated.
Nearly all names follow a snake_case max_<topic> pattern with a consistent, predictable prefix, which makes the set easy to scan. Minor deviations exist: several names are noun phrases (max_api_reference, max_limits, max_changelog) while others are verb_noun (max_lint_code, max_convert_formatting), max_bridge_mock reverses to noun_verb, and server_status drops the max_ prefix entirely.
21 tools is on the heavy side, but the server genuinely spans several sub-domains (API reference, scaffolding, linting, migration, message building, mocking, ads analytics), and almost every tool maps to a distinct job. There is little obvious redundancy, so the count is justified rather than padded, though a few reference tools could plausibly be merged.
The surface covers the full 'write correct MAX bot/mini-app code' lifecycle: look up facts, scaffold a project, build/validate messages, convert formatting, migrate from Telegram, mock updates and Bridge objects, and verify signatures, plus an ads/reporting branch. The notable gap is that nothing actually calls the live Bot API (no send-message or get-updates tool) and payments/upload execution are uncovered, so agents must hand-roll those steps.
Maintenance
Related MCP Connectors
Cross-posting between Telegram, MAX and VK: routes, copy rules, history import, chatbots.
Manage WhatsApp, Telegram and MAX mailings: audiences, drafts, moderation and sending.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Search 408K+ MAX channels and 86M+ posts; metrics, reactions, forwards, webhooks and usage.
Related MCP Servers
- AlicenseBqualityDmaintenanceFull-featured Telegram Bot API server for MCP (Model Context Protocol). 174 tools covering the entire Bot API — messages, chats, stickers, payments, forums, stories, and more.100334 npm7MIT
- FlicenseAqualityDmaintenanceAn MCP server for MAX Messenger (Russia's national messenger by VK) that enables AI clients to send and read messages, manage chats and members, send media, and more through 21 tools.2180 npm12-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to connect to a personal MAX account for QR-based sign-in, browsing chats and message history, sending messages and files, and safely downloading attachments via Docker and a stdio bridge.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to access a self-hosted MAX messenger personal account: browse chats, read and search message history, inspect context, pins and forwarded text, download attachments, and send text or files with receipts and retry protection. Also supports durable batch state for scheduled workflows, with local authentication and access control over Streamable HTTP.MIT