{
  "markdown": "# mcp-max-messenger\n\n[![npm version](https://badge.fury.io/js/%40woyax%2Fmcp-max-messenger.svg)](https://www.npmjs.com/package/@woyax/mcp-max-messenger)\n[![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT%20%2B%20Commons%20Clause-blue.svg)](https://github.com/woyaxnini/mcp-max-messenger/blob/main/LICENSE)\n\n**The first MCP server for MAX Messenger** — Russia's national messenger by VK (75M+ users).\n\nConnect 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](https://modelcontextprotocol.io) standard.\n\n**21 tools** with full coverage of MAX Bot API.\n\n---\n\n## Why MAX?\n\n- 🇷🇺 National messenger mandated for pre-installation on all smartphones in Russia (September 2025)\n- 📱 75M+ registered users\n- 🏢 Recommended by the Ministry of Digital Development for government agencies and large enterprises\n- 🤖 Full Bot API with official SDKs: TypeScript, Python, Go, Java, PHP\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- A MAX bot token (create a bot at [max.ru](https://max.ru))\n\n### Claude Desktop / Cursor (stdio mode)\n\nAdd to your Claude Desktop config:\n\n**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"max-messenger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@woyax/mcp-max-messenger\"],\n      \"env\": {\n        \"MAX_TOKEN\": \"YOUR_BOT_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The MAX tools will appear automatically.\n\n### Remote / Hosted mode (HTTP)\n\n```bash\nMAX_TOKEN=YOUR_BOT_TOKEN MCP_TRANSPORT=http MCP_PORT=3000 npx @woyax/mcp-max-messenger\n```\n\nConnect any MCP client to `http://your-server:3000/mcp`.\n\n---\n\n## Available Tools (21)\n\n### Messages\n\n| Tool | Description |\n|------|-------------|\n| `get_messages` | Read messages from a chat (by chat_id or message_ids) |\n| `send_message` | Send a message with text, HTML/Markdown, inline keyboard, media attachments |\n| `edit_message` | Edit message text and attachments |\n| `delete_message` | Delete a message |\n| `pin_message` | Pin a message in a chat |\n| `unpin_message` | Unpin the currently pinned message |\n\n### Media\n\n| Tool | Description |\n|------|-------------|\n| `send_media` | Upload and send photo, video, audio, or file by URL |\n| `send_action` | Show typing indicator, \"sending photo/video/audio/file\", mark as read |\n\n### Chats\n\n| Tool | Description |\n|------|-------------|\n| `get_bot_info` | Bot info: name, ID, username, description |\n| `get_chats` | List all group chats the bot participates in |\n| `get_chat` | Full chat details: participants, pinned message, owner |\n| `edit_chat` | Rename chat, change description or icon |\n\n### Members\n\n| Tool | Description |\n|------|-------------|\n| `get_chat_members` | List chat members with roles |\n| `get_admins` | List chat administrators with permissions |\n| `set_admin` | Grant admin rights to a member |\n| `remove_admin` | Revoke admin rights |\n| `add_members` | Add users to a group chat |\n| `remove_member` | Remove a user from a group chat |\n\n### Events\n\n| Tool | Description |\n|------|-------------|\n| `get_updates` | Incoming events: messages, button presses, new dialogs (long polling) |\n| `answer_callback` | Respond to inline button press: show notification or update message |\n\n### Buttons (via send_message attachments)\n\n5 button types supported: `callback`, `link`, `message`, `request_contact`, `request_geo_location`.\n\n---\n\n## Usage Examples\n\nOnce connected to Claude Desktop, use natural language:\n\n> *\"Send a message to chat 123456789: 'The meeting starts in 10 minutes'\"*\n\n> *\"Send an approval request with Approve/Reject buttons to the team chat\"*\n\n> *\"Show me the last 10 messages from the announcements chat\"*\n\n> *\"Send this photo to the chat: https://example.com/image.jpg\"*\n\n> *\"Who are the members of the sales group? Make Alex an admin.\"*\n\n> *\"Check for new incoming messages and button presses\"*\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `MAX_TOKEN` | ✅ | — | Your MAX bot token |\n| `MCP_TRANSPORT` | ❌ | `stdio` | Transport: `stdio` or `http` |\n| `MCP_PORT` | ❌ | `3000` | Port for HTTP mode |\n\n### Command-line Flags\n\n```bash\n# Local stdio mode (default)\nnpx @woyax/mcp-max-messenger\n\n# Remote HTTP mode\nnpx @woyax/mcp-max-messenger --transport http --port 3000\n```\n\n---\n\n## Architecture\n\nTwo independent layers — tools work identically in both modes:\n\n```\nsrc/\n├── core/               # Business logic — shared between modes\n│   ├── max-client.ts   # MAX API HTTP client\n│   ├── types.ts        # TypeScript types for MAX API\n│   └── tools/\n│       ├── bot.ts      # get_bot_info\n│       ├── chats.ts    # get_chats, get_chat, edit_chat, send_action\n│       ├── messages.ts # send/get/edit/delete/pin/unpin, send_media\n│       ├── members.ts  # get_chat_members, get_admins, set/remove_admin, add/remove_members\n│       └── updates.ts  # get_updates, answer_callback\n├── transports/         # Transport layer — selected at runtime\n│   ├── stdio.ts        # Local mode (Claude Desktop, Cursor)\n│   └── http.ts         # Remote mode (Streamable HTTP)\n└── index.ts            # Entry point: transport selection\n```\n\n---\n\n## MAX API Notes\n\n- **Authorization**: Token passed as `Authorization: <token>` — **no `Bearer` prefix**\n- **Base URL**: `https://platform-api.max.ru`\n- **Rate limit**: 30 requests/second\n- **Group chats**: `GET /chats` returns group chats only\n- **Personal dialogs**: Accessible via `get_updates` — use the returned `chat_id` with all standard tools\n- **Media upload**: Two-step process (upload → send). Audio/video tokens come from the upload step, not the file transfer\n- **HTTP transport**: Uses Streamable HTTP (SSE deprecated since MCP SDK 1.10.0)\n\n### Known MAX API Issues\n\n- `remove_admin` may return `success: true` without actually revoking rights — confirmed bug on MAX side\n- `open_app` button type returns \"Field 'webApp' cannot be null\" — MAX API bug\n- `add_members` may fail with `add.participant.privacy` if the user has privacy mode enabled\n\n---\n\n## Roadmap\n\n- [ ] HTTP mode testing on VPS with n8n integration\n- [ ] Hosted MCP service (connect by URL, no local install)\n- [ ] Webhook support for real-time event handling\n- [ ] `answer_callback` testing via n8n webhook workflow\n\n---\n\n## Links\n\n- [MAX Bot API Documentation](https://dev.max.ru/docs-api)\n- [MAX OpenAPI Schema](https://github.com/max-messenger/max-bot-api-schema)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [npm package](https://www.npmjs.com/package/@woyax/mcp-max-messenger)\n- [Russian README](./README.ru.md)\n\n---\n\n## Author & Support\n\nBuilt by **Oleg Alekseev** — ERP/AI integration architect.\n\n- 📧 woyaxnini@gmail.com · woyax@yandex.com\n- 💬 Telegram: [@ale_oleg](https://t.me/ale_oleg) · Channel: [@woyax_ai](https://t.me/woyax_ai)\n- 💬 MAX: [max.ru/id503610654564_biz](https://max.ru/id503610654564_biz)\n\nNeed help integrating AI agents with your ERP, CRM, or MAX? Custom MCP servers, n8n workflows, AI automation — [contact me](mailto:woyaxnini@gmail.com).\n\n---\n\n## License\n\nMIT + Commons Clause © [Oleg Alekseev](https://github.com/woyaxnini)\n\nFree to use for personal and corporate purposes. Selling as a hosted service requires author's permission. See [LICENSE](./LICENSE) for details.\n",
  "bytes": 7537,
  "sha": "636896f2dfbe8a9c19e11a9e7101f1a1666088d3c7dfb2290ecb293dd3c5661d",
  "repo_slug": "woyaxnini/mcp-max-messenger",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_woyaxnini_max_messenger_2af0c94d/readme"
}