Skip to main content
Glama

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

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

Available Tools

21 tools
max_ad_reportA
Read-onlyIdempotent
Inspect

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_referenceA
Read-onlyIdempotent
Inspect

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_mockA
Read-only
Inspect

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_messageA
Read-onlyIdempotent
Inspect

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_changelogB
Read-onlyIdempotent
Inspect

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_postA
Read-onlyIdempotent
Inspect

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_secretA
Read-onlyIdempotent
Inspect

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_formattingA
Read-onlyIdempotent
Inspect

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_endpoint_infoA
Read-onlyIdempotent
Inspect

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_limitsA
Read-onlyIdempotent
Inspect

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_codeA
Read-onlyIdempotent
Inspect

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_telegramA
Read-onlyIdempotent
Inspect

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_dataA
Read-only
Inspect

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_updateA
Read-only
Inspect

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_botA
Read-only
Inspect

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_textB
Read-onlyIdempotent
Inspect

Split text into MAX messages of at most 4000 characters, cutting at paragraphs, lines or sentences.

Inputs: text (required), lang, limit.

max_validate_messageA
Read-onlyIdempotent
Inspect

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_signatureA
Read-onlyIdempotent
Inspect

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_statusB
Read-onlyIdempotent
Inspect

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

    A3.7/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Full-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.
      100
      334 npm
      7
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An 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.
      21
      80 npm
      12
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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