MAX Personal MCP

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

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

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

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

Возможности

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

Related MCP server: apple-messages-mcp-remote

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

Нужны 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 и остальные зависимости распространяются под собственными лицензиями; их исходники и сессии не включены в репозиторий.