mcp-max-messenger

mcp-max-messenger

O primeiro servidor MCP para o MAX Messenger — o mensageiro nacional da Rússia, desenvolvido pela VK (mais de 75 milhões de usuários).

Conecte clientes de IA (Claude Desktop, Cursor, n8n e qualquer aplicativo compatível com MCP) ao MAX: envie e leia mensagens, gerencie chats e membros, envie mídia, lide com pressionamentos de botões, formate com HTML/Markdown — tudo por meio do padrão aberto Model Context Protocol.

21 ferramentas com cobertura completa da API de Bot do MAX.

---

Por que MAX?

• 🇷🇺 Mensageiro nacional com instalação obrigatória em todos os smartphones na Rússia (setembro de 2025)
• 📱 Mais de 75 milhões de usuários registrados
• 🏢 Recomendado pelo Ministério do Desenvolvimento Digital para órgãos governamentais e grandes empresas
• 🤖 API de Bot completa com SDKs oficiais: TypeScript, Python, Go, Java, PHP

---

Início Rápido

Pré-requisitos

• Node.js 18+
• Um token de bot do MAX (crie um bot em max.ru)

Claude Desktop / Cursor (modo stdio)

Adicione à configuração do seu 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"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas do MAX aparecerão automaticamente.

Modo remoto / hospedado (HTTP)

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

Conecte qualquer cliente MCP a http://your-server:3000/mcp.

---

Ferramentas Disponíveis (21)

Mensagens

Ferramenta	Descrição
get_messages	Ler mensagens de um chat (por chat_id ou message_ids)
send_message	Enviar uma mensagem com texto, HTML/Markdown, teclado inline, anexos de mídia
edit_message	Editar texto e anexos de uma mensagem
delete_message	Excluir uma mensagem
pin_message	Fixar uma mensagem em um chat
unpin_message	Desafixar a mensagem atualmente fixada

Mídia

Ferramenta	Descrição
send_media	Enviar e carregar foto, vídeo, áudio ou arquivo por URL
send_action	Mostrar indicador de digitação, "enviando foto/vídeo/áudio/arquivo", marcar como lido

Chats

Ferramenta	Descrição
get_bot_info	Informações do bot: nome, ID, nome de usuário, descrição
get_chats	Listar todos os chats em grupo dos quais o bot participa
get_chat	Detalhes completos do chat: participantes, mensagem fixada, proprietário
edit_chat	Renomear chat, alterar descrição ou ícone

Membros

Ferramenta	Descrição
get_chat_members	Listar membros do chat com funções
get_admins	Listar administradores do chat com permissões
set_admin	Conceder direitos de administrador a um membro
remove_admin	Revogar direitos de administrador
add_members	Adicionar usuários a um chat em grupo
remove_member	Remover um usuário de um chat em grupo

Eventos

Ferramenta	Descrição
get_updates	Eventos recebidos: mensagens, pressionamentos de botões, novos diálogos (long polling)
answer_callback	Responder a pressionamento de botão inline: mostrar notificação ou atualizar mensagem

Botões (via anexos de send_message)

5 tipos de botões suportados: callback, link, message, request_contact, request_geo_location.

---

Exemplos de Uso

Depois de conectado ao Claude Desktop, use linguagem natural:

"Envie uma mensagem para o chat 123456789: 'A reunião começa em 10 minutos'"

"Envie uma solicitação de aprovação com botões Aprovar/Rejeitar para o chat da equipe"

"Mostre-me as últimas 10 mensagens do chat de avisos"

"Envie esta foto para o chat: https://example.com/image.jpg"

"Quem são os membros do grupo de vendas? Torne o Alex um administrador."

"Verifique se há novas mensagens recebidas e pressionamentos de botões"

---

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
MAX_TOKEN	✅	—	Seu token de bot do MAX
MCP_TRANSPORT	❌	stdio	Transporte: stdio ou http
MCP_PORT	❌	3000	Porta para o modo HTTP

Flags de Linha de Comando

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

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

---

Arquitetura

Duas camadas independentes — as ferramentas funcionam de forma idêntica em ambos os modos:

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

---

Notas sobre a API do MAX

• Autorização: Token passado como Authorization: <token> — sem prefixo Bearer
• URL base: https://platform-api.max.ru
• Limite de taxa: 30 solicitações/segundo
• Chats em grupo: GET /chats retorna apenas chats em grupo
• Diálogos pessoais: Acessíveis via get_updates — use o chat_id retornado com todas as ferramentas padrão
• Upload de mídia: Processo em duas etapas (upload → envio). Tokens de áudio/vídeo vêm da etapa de upload, não da transferência de arquivo
• Transporte HTTP: Usa Streamable HTTP (SSE descontinuado desde o MCP SDK 1.10.0)

Problemas Conhecidos da API do MAX

• remove_admin pode retornar success: true sem realmente revogar os direitos — bug confirmado no lado do MAX
• O tipo de botão open_app retorna "Field 'webApp' cannot be null" — bug da API do MAX
• add_members pode falhar com add.participant.privacy se o usuário tiver o modo de privacidade ativado

---

Roadmap

• Teste do modo HTTP em VPS com integração n8n
• Serviço MCP hospedado (conecte por URL, sem instalação local)
• Suporte a webhooks para tratamento de eventos em tempo real
• Teste de answer_callback via fluxo de trabalho de webhook do n8n

---

Links

• Documentação da API de Bot do MAX
• Esquema OpenAPI do MAX
• Model Context Protocol
• Pacote npm
• README em russo

---

Autor e Suporte

Desenvolvido por Oleg Alekseev — arquiteto de integração ERP/IA.

• 📧 woyaxnini@gmail.com · woyax@yandex.com
• 💬 Telegram: @ale_oleg · Canal: @woyax_ai
• 💬 MAX: max.ru/id503610654564_biz

Precisa de ajuda para integrar agentes de IA ao seu ERP, CRM ou MAX? Servidores MCP personalizados, fluxos de trabalho n8n, automação de IA — entre em contato.

---

Licença

MIT + Commons Clause © Oleg Alekseev

Uso gratuito para fins pessoais e corporativos. A venda como serviço hospedado requer permissão do autor. Consulte LICENSE para detalhes.