mcp-max-messenger

mcp-max-messenger

El primer servidor MCP para MAX Messenger — el mensajero nacional de Rusia de VK (más de 75M de usuarios).

Conecta clientes de IA (Claude Desktop, Cursor, n8n y cualquier aplicación compatible con MCP) a MAX: envía y lee mensajes, gestiona chats y miembros, envía multimedia, maneja pulsaciones de botones, formatea con HTML/Markdown — todo a través del estándar abierto Model Context Protocol.

21 herramientas con cobertura completa de la API de MAX Bot.

---

¿Por qué MAX?

• 🇷🇺 Mensajero nacional obligatorio para preinstalación en todos los smartphones de Rusia (septiembre de 2025)
• 📱 Más de 75M de usuarios registrados
• 🏢 Recomendado por el Ministerio de Desarrollo Digital para agencias gubernamentales y grandes empresas
• 🤖 API de Bot completa con SDKs oficiales: TypeScript, Python, Go, Java, PHP

---

Inicio Rápido

Requisitos previos

• Node.js 18+
• Un token de bot de MAX (crea un bot en max.ru)

Claude Desktop / Cursor (modo stdio)

Añade a tu configuración de 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"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de MAX aparecerán automáticamente.

Modo remoto / alojado (HTTP)

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

Conecta cualquier cliente MCP a http://your-server:3000/mcp.

---

Herramientas Disponibles (21)

Mensajes

Herramienta	Descripción
get_messages	Leer mensajes de un chat (por chat_id o message_ids)
send_message	Enviar un mensaje con texto, HTML/Markdown, teclado en línea, adjuntos multimedia
edit_message	Editar texto y adjuntos de un mensaje
delete_message	Eliminar un mensaje
pin_message	Fijar un mensaje en un chat
unpin_message	Desfijar el mensaje actualmente fijado

Multimedia

Herramienta	Descripción
send_media	Subir y enviar foto, video, audio o archivo por URL
send_action	Mostrar indicador de escritura, "enviando foto/video/audio/archivo", marcar como leído

Chats

Herramienta	Descripción
get_bot_info	Información del bot: nombre, ID, nombre de usuario, descripción
get_chats	Listar todos los chats grupales en los que participa el bot
get_chat	Detalles completos del chat: participantes, mensaje fijado, propietario
edit_chat	Renombrar chat, cambiar descripción o icono

Miembros

Herramienta	Descripción
get_chat_members	Listar miembros del chat con roles
get_admins	Listar administradores del chat con permisos
set_admin	Otorgar derechos de administrador a un miembro
remove_admin	Revocar derechos de administrador
add_members	Añadir usuarios a un chat grupal
remove_member	Eliminar un usuario de un chat grupal

Eventos

Herramienta	Descripción
get_updates	Eventos entrantes: mensajes, pulsaciones de botones, nuevos diálogos (long polling)
answer_callback	Responder a pulsación de botón en línea: mostrar notificación o actualizar mensaje

Botones (vía adjuntos de send_message)

5 tipos de botones compatibles: callback, link, message, request_contact, request_geo_location.

---

Ejemplos de Uso

Una vez conectado a Claude Desktop, usa lenguaje natural:

"Envía un mensaje al chat 123456789: 'La reunión comienza en 10 minutos'"

"Envía una solicitud de aprobación con botones Aprobar/Rechazar al chat del equipo"

"Muéstrame los últimos 10 mensajes del chat de anuncios"

"Envía esta foto al chat: https://example.com/image.jpg"

"¿Quiénes son los miembros del grupo de ventas? Haz a Alex administrador."

"Comprueba si hay nuevos mensajes entrantes y pulsaciones de botones"

---

Configuración

Variables de Entorno

Variable	Requerida	Predeterminado	Descripción
MAX_TOKEN	✅	—	Tu token de bot de MAX
MCP_TRANSPORT	❌	stdio	Transporte: stdio o http
MCP_PORT	❌	3000	Puerto para modo HTTP

Banderas de Línea de Comandos

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

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

---

Arquitectura

Dos capas independientes — las herramientas funcionan de forma idéntica en ambos 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 de la API de MAX

• Autorización: Token pasado como Authorization: <token> — sin prefijo Bearer
• URL base: https://platform-api.max.ru
• Límite de velocidad: 30 solicitudes/segundo
• Chats grupales: GET /chats devuelve solo chats grupales
• Diálogos personales: Accesibles vía get_updates — usa el chat_id devuelto con todas las herramientas estándar
• Subida de multimedia: Proceso de dos pasos (subir → enviar). Los tokens de audio/video provienen del paso de subida, no de la transferencia de archivos
• Transporte HTTP: Usa Streamable HTTP (SSE obsoleto desde MCP SDK 1.10.0)

Problemas conocidos de la API de MAX

• remove_admin puede devolver success: true sin revocar realmente los derechos — error confirmado del lado de MAX
• El tipo de botón open_app devuelve "Field 'webApp' cannot be null" — error de la API de MAX
• add_members puede fallar con add.participant.privacy si el usuario tiene el modo de privacidad activado

---

Hoja de Ruta

• Pruebas de modo HTTP en VPS con integración n8n
• Servicio MCP alojado (conectar por URL, sin instalación local)
• Soporte de webhooks para manejo de eventos en tiempo real
• Pruebas de answer_callback mediante flujo de trabajo webhook de n8n

---

Enlaces

• Documentación de la API de MAX Bot
• Esquema OpenAPI de MAX
• Model Context Protocol
• Paquete npm
• README en ruso

---

Autor y Soporte

Creado por Oleg Alekseev — arquitecto de integración ERP/IA.

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

¿Necesitas ayuda integrando agentes de IA con tu ERP, CRM o MAX? Servidores MCP personalizados, flujos de trabajo n8n, automatización con IA — contáctame.

---

Licencia

MIT + Commons Clause © Oleg Alekseev

Uso gratuito para fines personales y corporativos. La venta como servicio alojado requiere permiso del autor. Consulta LICENSE para más detalles.