Max Messenger

mcp-max-messenger

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.

Why MAX?

• 🇷🇺 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

Quick Start

Prerequisites

• Node.js 18+
• A MAX bot token (create a bot at max.ru)

Claude Desktop / Cursor (stdio mode)

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.

Remote / Hosted mode (HTTP)

MAX_TOKEN=YOUR_BOT_TOKEN MCP_TRANSPORT=http MCP_PORT=3000 npx @woyax/mcp-max-messenger

Connect any MCP client to http://your-server:3000/mcp.

Available Tools (21)

Messages

Media

Chats

Members

Events

Buttons (via send_message attachments)

5 button types supported: callback, link, message, request_contact, request_geo_location.

Usage Examples

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"*

Configuration

Environment Variables

Command-line Flags

# Local stdio mode (default)

npx @woyax/mcp-max-messenger

Remote HTTP mode

npx @woyax/mcp-max-messenger --transport http --port 3000

Architecture

Two 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 selection

MAX API Notes

• Authorization: Token passed as Authorization: — 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)

Known MAX API Issues

• 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

Roadmap

• 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

Links

• MAX Bot API Documentation
• MAX OpenAPI Schema
• Model Context Protocol
• npm package
• Russian README

Author & Support

Built by Oleg Alekseev — ERP/AI integration architect.

• 📧 woyaxnini@gmail.com · woyax@yandex.com
• 💬 Telegram: @ale_oleg · Channel: @woyax_ai
• 💬 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.

License

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.