Skip to main content
Glama
MAX Personal MCP

MAX Personal MCP

by Uralmans

MAX Personal MCP

CI

Личный MAX в вашем AI-ассистенте: чаты, история, сообщения и файлы через MCP.

English · Установка и эксплуатация · Передача файлов · Безопасность

Локальный сервер Model Context Protocol для личной учётной записи MAX. Работает в Docker, подключается через QR-код и хранит сессию в отдельном томе. Для Codex и других MCP-клиентов предусмотрен stdio-мост: секрет доступа остаётся внутри контейнера.

Независимый проект, не связанный с MAX и его правообладателями. Используется неофициальный PyMax, а не Bot API. Изменения сервиса могут нарушить совместимость. Проверяйте правила MAX и используйте собственный аккаунт.

Возможности

Инструмент

Назначение

account_status

Состояние подключения и адрес локального входа

get_me

Профиль текущего пользователя

list_chats

Поиск и список чатов из кеша синхронизации

get_chat

Информация о чате по ID

read_messages

История без отдельной команды отметки прочтения

get_user

Профиль участника по ID

send_message

Текст, в том числе ответ на сообщение

send_file

Локальный файл, подпись и ответ на сообщение

download_file

Скачивание вложения с проверкой размера

Отправка разрешена только по прямому поручению пользователя. При неизвестном результате сначала проверяется история — автоматических повторов после сетевого сбоя нет. Чат 0 используется для «Избранного»; перед первой отправкой проверьте его через get_chat.

Related MCP server: weskill

Быстрый старт

Нужны Docker Engine с Compose v2 (или Docker Desktop), Python 3.10+ для вспомогательного скрипта и аккаунт MAX на телефоне. Linux-контейнер не зависит от ОС хоста; проверка реального MAX выполнена на Docker Desktop для macOS. Windows и Linux требуют отдельной проверки в вашей среде.

git clone https://github.com/Uralmans/max-personal-mcp.git
cd max-personal-mcp
python3 scripts/transfer.py status
docker compose up -d --build

Откройте локальную страницу входа, запросите QR-код и подтвердите подключение в MAX на телефоне. Если потребуется пароль аккаунта, введите его только на локальной странице. Дождитесь подтверждения подключения.

Папка передачи создаётся командой status до запуска Compose. Она подключается только для чтения. Переменные прокси необязательны: при необходимости скопируйте .env.example в .env и укажите MAX_PROXY. Не публикуйте этот файл.

Подключение к MCP-клиенту

Общая конфигурация клиента с поддержкой stdio:

{
  "mcpServers": {
    "max": {
      "command": "docker",
      "args": ["exec", "-i", "max-mcp", "python", "/app/bridge.py"]
    }
  }
}

Убедитесь, что Docker CLI доступен MCP-клиенту. После настройки переподключите сервер или откройте новый чат. Контейнер должен быть запущен и авторизован.

Схема соединения:

MCP-клиент → docker exec / stdio → мост → локальный MCP-сервер → MAX
                                             │
                                  сессия в Docker volume

Отправить файл

python3 scripts/transfer.py stage /path/to/report.zip

Скрипт вернёт путь /transfer/<job>/000/report.zip, размер и SHA-256. Передайте путь в send_file, затем проверьте имя и размер вложения в истории чата. Только после проверки удалите временную копию через finish. Подробности и команды для Windows: передача файлов.

Расширению доступа ко всему диску этот сценарий не требует. Исходники файлов остаются на месте. Лимит допуска файла — 2 ГБ; фактический успех зависит от сервиса, сети, тайм-аутов и свободного места.

Что защищено

  • Порт опубликован только на 127.0.0.1; MCP требует Bearer-ключ, который читает мост.

  • Для браузерного входа проверяются Host и Origin, QR и статус не кешируются.

  • Контейнер работает без root, с файловой системой только для чтения и без Linux capabilities.

  • У загрузки есть отдельная папка; выход через .., ссылки и специальные файлы отклоняются.

  • Учётные данные, .env, файлы сессий, QR, результаты и временные копии исключены из Git. Docker build использует список разрешённых файлов.

При этом доверенный MCP-клиент получает доступ к личным сообщениям и может выполнять разрешённые отправки. Это локальный сервис для одного владельца, без отдельных ролей и учёта полномочий разных пользователей. Подробнее: SECURITY.md.

Проверки

docker compose build
docker run --rm --read-only --tmpfs /tmp -v "$PWD/tests:/tests:ro" \
  local/max-personal-mcp:0.2.0 python -m unittest discover -s /tests -v
docker exec max-mcp python /app/probe.py
python3 scripts/check_public_files.py

22 автоматических теста проверяют границы доступа, работу с файлами и ошибки без обращения к MAX. В рабочей среде дополнительно подтверждена отправка ZIP в «Избранное»: сообщение найдено в истории, скачанное вложение совпало с оригиналом по SHA-256. Это не проверка всех форматов файлов и размеров до 2 ГБ. В CI личный аккаунт и секреты не используются.

Документация и участие

Лицензия: MIT. PyMax и остальные зависимости распространяются под собственными лицензиями; их исходники и сессии не включены в репозиторий.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables connecting a personal MAX messenger account to MCP clients for reading chats, message history, searching messages, summarizing unread chats, and accessing contacts, with optional write tools disabled by default.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables compatible AI assistants to operate Linux WeChat through local stdio, including contact and group search, bounded message history retrieval, private and group text sending, shared service lifecycle management, capability discovery, and persistent idempotent deduplication.
      2
      20 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access a self-hosted MAX messenger personal account: browse chats, read and search message history, inspect context, pins and forwarded text, download attachments, and send text or files with receipts and retry protection. Also supports durable batch state for scheduled workflows, with local authentication and access control over Streamable HTTP.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables ChatGPT, Claude, Cursor, and other MCP clients to read and send messages, manage chats, groups, media, polls, and profiles in a user's personal Telegram and MAX accounts via a self-hosted server.
      1
      MIT