mcp-max-messenger

mcp-max-messenger

GitHub

mcp-max-messenger

npm version License: MIT + Commons Clause

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

ToolDescription
get_messagesRead messages from a chat (by chat_id or message_ids)
send_messageSend a message with text, HTML/Markdown, inline keyboard, media attachments
edit_messageEdit message text and attachments
delete_messageDelete a message
pin_messagePin a message in a chat
unpin_messageUnpin the currently pinned message

Media

ToolDescription
send_mediaUpload and send photo, video, audio, or file by URL
send_actionShow typing indicator, "sending photo/video/audio/file", mark as read

Chats

ToolDescription
get_bot_infoBot info: name, ID, username, description
get_chatsList all group chats the bot participates in
get_chatFull chat details: participants, pinned message, owner
edit_chatRename chat, change description or icon

Members

ToolDescription
get_chat_membersList chat members with roles
get_adminsList chat administrators with permissions
set_adminGrant admin rights to a member
remove_adminRevoke admin rights
add_membersAdd users to a group chat
remove_memberRemove a user from a group chat

Events

ToolDescription
get_updatesIncoming events: messages, button presses, new dialogs (long polling)
answer_callbackRespond 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

VariableRequiredDefaultDescription
MAX_TOKEN✅—Your MAX bot token
MCP_TRANSPORT❌stdioTransport: stdio or http
MCP_PORT❌3000Port 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

Author & Support

Built by Oleg Alekseev — ERP/AI integration architect.

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.

Server Terkait