Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-max-messenger Send a message to chat 123456789: 'The meeting starts in 10 minutes'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The first MCP server for MAX Messenger β Russia's national messenger by VK (75M+ users).
Connect AI clients (Claude Desktop, Cursor, n8n, and any MCP-compatible app) to MAX: send and read messages, manage chats and members, send media, handle button presses, format with HTML/Markdown β all through the open Model Context Protocol standard.
21 tools with full coverage of MAX Bot API.
π·πΊ National messenger mandated for pre-installation on all smartphones in Russia (September 2025)
π± 75M+ registered users
π’ Recommended by the Ministry of Digital Development for government agencies and large enterprises
π€ Full Bot API with official SDKs: TypeScript, Python, Go, Java, PHP
Related MCP server: time-messenger-mcp-server
Node.js 18+
A MAX bot token (create a bot at max.ru)
Add to your Claude Desktop config:
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"max-messenger": {
"command": "npx",
"args": ["-y", "@woyax/mcp-max-messenger"],
"env": {
"MAX_TOKEN": "YOUR_BOT_TOKEN"
}
}
}
}Restart Claude Desktop. The MAX tools will appear automatically.
MAX_TOKEN=YOUR_BOT_TOKEN MCP_TRANSPORT=http MCP_PORT=3000 npx @woyax/mcp-max-messengerConnect any MCP client to http://your-server:3000/mcp.
Tool | Description |
| Read messages from a chat (by chat_id or message_ids) |
| Send a message with text, HTML/Markdown, inline keyboard, media attachments |
| Edit message text and attachments |
| Delete a message |
| Pin a message in a chat |
| Unpin the currently pinned message |
Tool | Description |
| Upload and send photo, video, audio, or file by URL |
| Show typing indicator, "sending photo/video/audio/file", mark as read |
Tool | Description |
| Bot info: name, ID, username, description |
| List all group chats the bot participates in |
| Full chat details: participants, pinned message, owner |
| Rename chat, change description or icon |
Tool | Description |
| List chat members with roles |
| List chat administrators with permissions |
| Grant admin rights to a member |
| Revoke admin rights |
| Add users to a group chat |
| Remove a user from a group chat |
Tool | Description |
| Incoming events: messages, button presses, new dialogs (long polling) |
| Respond to inline button press: show notification or update message |
5 button types supported: callback, link, message, request_contact, request_geo_location.
Once connected to Claude Desktop, use natural language:
"Send a message to chat 123456789: 'The meeting starts in 10 minutes'"
"Send an approval request with Approve/Reject buttons to the team chat"
"Show me the last 10 messages from the announcements chat"
"Send this photo to the chat: https://example.com/image.jpg"
"Who are the members of the sales group? Make Alex an admin."
"Check for new incoming messages and button presses"
Variable | Required | Default | Description |
| β | β | Your MAX bot token |
| β |
| Transport: |
| β |
| Port for HTTP mode |
# Local stdio mode (default)
npx @woyax/mcp-max-messenger
# Remote HTTP mode
npx @woyax/mcp-max-messenger --transport http --port 3000Two independent layers β tools work identically in both modes:
src/
βββ core/ # Business logic β shared between modes
β βββ max-client.ts # MAX API HTTP client
β βββ types.ts # TypeScript types for MAX API
β βββ tools/
β βββ bot.ts # get_bot_info
β βββ chats.ts # get_chats, get_chat, edit_chat, send_action
β βββ messages.ts # send/get/edit/delete/pin/unpin, send_media
β βββ members.ts # get_chat_members, get_admins, set/remove_admin, add/remove_members
β βββ updates.ts # get_updates, answer_callback
βββ transports/ # Transport layer β selected at runtime
β βββ stdio.ts # Local mode (Claude Desktop, Cursor)
β βββ http.ts # Remote mode (Streamable HTTP)
βββ index.ts # Entry point: transport selectionAuthorization: Token passed as Authorization: <token> β no Bearer prefix
Base URL: https://platform-api.max.ru
Rate limit: 30 requests/second
Group chats: GET /chats returns group chats only
Personal dialogs: Accessible via get_updates β use the returned chat_id with all standard tools
Media upload: Two-step process (upload β send). Audio/video tokens come from the upload step, not the file transfer
HTTP transport: Uses Streamable HTTP (SSE deprecated since MCP SDK 1.10.0)
remove_admin may return success: true without actually revoking rights β confirmed bug on MAX side
open_app button type returns "Field 'webApp' cannot be null" β MAX API bug
add_members may fail with add.participant.privacy if the user has privacy mode enabled
HTTP mode testing on VPS with n8n integration
Hosted MCP service (connect by URL, no local install)
Webhook support for real-time event handling
answer_callback testing via n8n webhook workflow
Built by Oleg Alekseev β ERP/AI integration architect.
π§ woyaxnini@gmail.com Β· woyax@yandex.com
π¬ MAX: max.ru/id503610654564_biz
Need help integrating AI agents with your ERP, CRM, or MAX? Custom MCP servers, n8n workflows, AI automation β contact me.
MIT + Commons Clause Β© Oleg Alekseev
Free to use for personal and corporate purposes. Selling as a hosted service requires author's permission. See LICENSE for details.
Add one or more users to a group chat. The bot must be an admin of the chat. Provide user_ids to add.
Inputs: chat_id (required), user_ids (required).
Respond to an inline button click (callback event from get_updates). You can update the original message text and/or show a notification popup to the user. Must be called within 30 seconds of the button press.
Inputs: callback_id (required), user_id (required), notification, message_text, +1 more.
Delete a message sent by the bot. Requires the message_id.
Inputs: message_id (required).
Rename a chat, change its description, or update its icon. The bot must be an admin of the chat.
Inputs: chat_id (required), title, description, icon, +1 more.
Edit the text of an existing message sent by the bot. Optionally update attachments (inline keyboard buttons). Requires the message_id.
Inputs: message_id (required), text (required), format, attachments.
Get the list of administrators in a group chat. Returns user_id, name, username, and permissions for each admin.
Inputs: chat_id (required).
Get information about the MAX bot: name, username, user_id, description. Use this to verify the bot is connected and working.
Inputs: no named parameters.
Get full details of a specific chat by its ID: title, description, participant count, icon, pinned message, link.
Inputs: chat_id (required).
Get the list of participants in a group chat. Returns user_id, name, username for each member.
Inputs: chat_id (required), count, marker.
Get the list of all group chats where the bot is a participant. Returns chat_id, title, type, participant count, and last activity time. Use chat_id from results to read or send messages. NOTE: Only group chats are returned. Personal dialogs (type: dialog) are NOT included here β use get_updates to discover their chat_id.
Inputs: count, marker.
Get a single message by its ID. Returns full message details including text, sender, attachments.
Inputs: message_id (required).
Read messages from a MAX chat. Use either chat_id OR message_ids β they are mutually exclusive. With chat_id: returns recent messages from that chat (use count/from/to to filter). With message_ids: returns those specific messages only (do NOT provide chat_id).
Inputs: chat_id, count, from, to, +1 more.
Get incoming events: new messages, button clicks, user joins/leaves, etc. This is the ONLY way to get chat_id for personal dialogs (type: dialog). Use the returned marker in the next call to get only new events. Set timeout=0 for instant response, timeout>0 for long polling (waits up to N seconds for new events). Event types: message_created, message_edited, message_removed, message_callback, bot_started, bot_added, bot_removed, user_added, user_removed, message_chat_created. NOTE: Designed for development and manual polling only. For production bots use webhooks (POST /subscriptions) β in production the update queue accumulates quickly without continuous processing.
Inputs: limit, timeout, marker, types.
Pin a message in a group chat. The bot must have admin rights in the chat.
Inputs: chat_id (required), message_id (required), notify.
Revoke admin rights from a chat member. They remain a regular member. The bot must be an admin or owner of the chat. KNOWN MAX API BUG: The API returns success:true but rights may not actually be revoked. This is a confirmed issue on the MAX side β only the chat owner can reliably remove admin rights manually in the app.
Inputs: chat_id (required), user_id (required).
Remove a user from a group chat. The bot must be an admin of the chat. Optionally block the user from rejoining. WARNING: If the user has privacy mode enabled in MAX settings, the bot will not be able to re-add them after removal β confirm with the user before proceeding.
Inputs: chat_id (required), user_id (required), block.
Show a typing indicator or other status to chat members. Use before sending a message to improve UX. Actions: typing_on, sending_photo, sending_video, sending_audio, sending_file, mark_seen.
Inputs: chat_id (required), action (required).
Upload a file (image/video/audio/file) from a URL and send it as a message. The tool handles the full two-step upload process automatically: 1) get MAX upload URL, 2) upload file, 3) send message with attachment. Provide either chat_id or user_id.
Inputs: file_url (required), type (required), chat_id, user_id, +2 more.
Send a text message to a MAX chat or user. Provide either chat_id (group chats/channels) or user_id (direct messages), not both. Supports markdown and HTML formatting. Use attachments to add inline keyboard buttons or media (use tokens from send_media).
Inputs: text (required), chat_id, user_id, format, +3 more.
Grant admin rights to a chat member. The bot must be an admin or owner of the chat.
Inputs: chat_id (required), user_id (required).
Unpin the currently pinned message in a group chat. The bot must have admin rights.
Inputs: chat_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
Scored across 21 tools
Each tool targets a distinct operationβmessaging, chat management, admin actions, updates, etc. There is no overlap; even similar tools like get_message vs get_messages are clearly separated by singular vs plural access patterns.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., send_message, get_chats, remove_admin). The convention is uniform across all 21 tools, making it easy to predict tool functions.
21 tools is well-scoped for a messaging bot server. It covers essential messaging, chat management, admin functions, updates polling, and media sending without being bloated or insufficient.
The tool surface covers core CRUD for messages, chat management, and admin roles. Missing are create_chat/delete_chat and webhook setup, but these are not critical for basic bot operations and can be handled externally.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI dialogue using various LLM models via AceDataCloud
