max-messenger

mcp-max-messenger

首个面向 MAX Messenger 的 MCP 服务——VK 推出的俄罗斯国家级即时通讯应用（拥有 7,500 万以上用户）。

通过开放的 Model Context Protocol 标准，将 AI 客户端（Claude Desktop、Cursor、n8n 及任何兼容 MCP 的应用）连接到 MAX：发送和读取消息、管理聊天和成员、发送媒体、处理按钮点击、使用 HTML/Markdown 格式化等。

21 个工具，全面支持 MAX Bot API。

---

为什么选择 MAX？

• 🇷🇺 俄罗斯国家级即时通讯应用，规定自 2025 年 9 月起预装在所有智能手机上
• 📱 注册用户超过 7,500 万
• 🏢 数字发展部推荐政府机构和大型企业使用
• 🤖 完整的 Bot API，并提供官方 SDK：TypeScript、Python、Go、Java、PHP

---

快速开始

前置条件

• Node.js 18+
• MAX 机器人令牌（在 max.ru 创建机器人）

Claude Desktop / Cursor（stdio 模式）

添加到 Claude Desktop 配置文件：

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

重启 Claude Desktop。MAX 工具将自动显示。

远程 / 托管模式（HTTP）

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

将任意 MCP 客户端连接到 http://your-server:3000/mcp。

---

可用工具（21 个）

消息

工具	描述
get_messages	从聊天中读取消息（通过 chat_id 或 message_ids）
send_message	发送包含文本、HTML/Markdown、内联键盘和媒体附件的消息
edit_message	编辑消息文本和附件
delete_message	删除消息
pin_message	在聊天中置顶消息
unpin_message	取消置顶当前置顶的消息

媒体

工具	描述
send_media	通过 URL 上传并发送照片、视频、音频或文件
send_action	显示正在输入、“正在发送照片/视频/音频/文件”指示，或标记为已读

聊天

工具	描述
get_bot_info	机器人信息：名称、ID、用户名、描述
get_chats	列出机器人参与的所有群聊
get_chat	聊天完整详情：参与者、置顶消息、所有者
edit_chat	重命名聊天、更改描述或图标

成员

工具	描述
get_chat_members	列出聊天成员及其角色
get_admins	列出聊天管理员及其权限
set_admin	授予成员管理员权限
remove_admin	撤销管理员权限
add_members	将用户添加到群聊
remove_member	从群聊中移除用户

事件

工具	描述
get_updates	收到的事件：消息、按钮点击、新对话（长轮询）
answer_callback	响应内联按钮点击：显示通知或更新消息

按钮（通过 send_message attachments 发送）

支持 5 种按钮类型：callback、link、message、request_contact、request_geo_location。

---

使用示例

连接到 Claude Desktop 后，使用自然语言：

“向聊天 123456789 发送消息：‘会议将在 10 分钟后开始’”

“向团队聊天发送带有‘批准/拒绝’按钮的审批请求”

“显示公告聊天中的最近 10 条消息”

“将这张照片发送到聊天：https://example.com/image.jpg”

“销售群里有哪些成员？把 Alex 设为管理员。”

“检查是否有新收到的消息和按钮点击”

---

配置

环境变量

变量	必需	默认值	描述
MAX_TOKEN	✅	—	你的 MAX 机器人令牌
MCP_TRANSPORT	❌	stdio	传输方式：stdio 或 http
MCP_PORT	❌	3000	HTTP 模式的端口

命令行标志

# Local stdio mode (default)
npx @woyax/mcp-max-messenger

# Remote HTTP mode
npx @woyax/mcp-max-messenger --transport http --port 3000

---

架构

两个独立层——两种模式下的工具运行方式完全相同：

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 说明

• 授权：令牌通过 Authorization: <token> 传递——不带 Bearer 前缀
• 基础 URL：https://platform-api.max.ru
• 速率限制：每秒 30 个请求
• 群聊：GET /chats 仅返回群聊
• 个人对话：可通过 get_updates 访问——将返回的 chat_id 与所有标准工具一起使用
• 媒体上传：分两步进行（上传 → 发送）。音频/视频令牌来自上传步骤，而非文件传输
• HTTP 传输：使用 Streamable HTTP（MCP SDK 1.10.0 起弃用 SSE）

已知的 MAX API 问题

• remove_admin 可能会返回 success: true，但实际上并未撤销权限——已确认是 MAX 端的错误
• open_app 按钮类型会返回 "Field 'webApp' cannot be null"——MAX API 错误
• 如果用户启用了隐私模式，add_members 可能会因 add.participant.privacy 而失败

---

路线图

• 在 VPS 上测试 HTTP 模式并集成 n8n
• 托管 MCP 服务（通过 URL 连接，无需本地安装）
• 支持 Webhook，以实时处理事件
• 通过 n8n Webhook 工作流测试 answer_callback

---

链接

• MAX 机器人 API 文档
• MAX OpenAPI Schema
• 模型上下文协议
• npm 包
• 俄语版 README

---

作者与支持

由 ERP/AI 集成架构师 Oleg Alekseev 构建。

• 📧 [email protected] · [email protected]
• 💬 Telegram： @ale_oleg · 频道：@woyax_ai
• 💬 MAX：max.ru/id503610654564_biz

需要将 AI Agent 集成到你的 ERP、CRM 或 MAX 中？定制 MCP 服务、n8n 工作流、AI 自动化——联系我。

---

许可证

MIT + Commons Clause © Oleg Alekseev

可免费用于个人和企业用途。将其作为托管服务出售需要获得作者许可。详情请参阅 LICENSE。