io.github.woyaxnini/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: <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.

• 📧 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.