Max Messenger

io.github.woyaxniniPublished by GitHub account woyaxniniv1.2.2Updated Oct 24, 2026

MCP server for MAX Messenger by VK. 21 tools: messages, media, buttons, members, events.

VerifiedSTDIODesktop onlyProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

A local MCP server for MAX Messenger (VK) that lets an assistant send, read, edit and manage messages, media, chats and members through a MAX bot.

What you can do
Read, send, edit, delete, pin and unpin messages, including HTML/Markdown text and inline buttons, and send photos, video, audio or files by URL with typing and read indicators via send_action. List chats, get chat details, and rename chats or change their description and icon. List members and administrators, grant or revoke admin rights, and add or remove group members. Poll incoming events such as messages and button presses, and answer inline button callbacks.
When to use it
Use it when an assistant should work inside MAX Messenger chats: posting announcements or approval requests with buttons, reading recent messages, sending media, or managing group membership and admins.
Requirements
Node.js 18+ and a local npm package run via npx. A MAX bot token created at max.ru, supplied in the MAX_TOKEN environment variable. Optional MCP_TRANSPORT (stdio or http) and MCP_PORT for hosted HTTP mode. Network access to the MAX API.
Before you install
The MAX_TOKEN bot token is a secret and is sent as a bare Authorization header without a Bearer prefix. Many tools write or change data: sending, editing and deleting messages, renaming chats, granting or revoking admin rights, and adding or removing members. The README notes that remove_admin may report success without actually revoking rights. HTTP mode exposes the server on a port.

Installation

In SourceWeft

  1. Open Max Messenger in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

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)

bash
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

bash
# Local stdio mode (default)npx @woyax/mcp-max-messenger
# Remote HTTP modenpx @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.

Source: README.md at commit 4a3233a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.2.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.