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

Tool	Description
get_messages	Read messages from a chat (by chat_id or message_ids)
send_message	Send a message with text, HTML/Markdown, inline keyboard, media attachments
edit_message	Edit message text and attachments
delete_message	Delete a message
pin_message	Pin a message in a chat
unpin_message	Unpin the currently pinned message

Media

Tool	Description
send_media	Upload and send photo, video, audio, or file by URL
send_action	Show typing indicator, "sending photo/video/audio/file", mark as read

Chats

Tool	Description
get_bot_info	Bot info: name, ID, username, description
get_chats	List all group chats the bot participates in
get_chat	Full chat details: participants, pinned message, owner
edit_chat	Rename chat, change description or icon

Members

Tool	Description
get_chat_members	List chat members with roles
get_admins	List chat administrators with permissions
set_admin	Grant admin rights to a member
remove_admin	Revoke admin rights
add_members	Add users to a group chat
remove_member	Remove a user from a group chat

Events

Tool	Description
get_updates	Incoming events: messages, button presses, new dialogs (long polling)
answer_callback	Respond to inline button press: show notification or update message

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

Variable	Required	Default	Description
MAX_TOKEN	✅	—	Your MAX bot token
MCP_TRANSPORT	❌	stdio	Transport: stdio or http
MCP_PORT	❌	3000	Port for HTTP mode

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: <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)

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.

• 📧 [email protected] · [email protected]
• 💬 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.