tg-max-mcp

tg-max-mcp — MCP-сервер, который даёт ChatGPT, Claude, Cursor и другим ассистентам доступ к вашему личному аккаунту Telegram и MAX. Пишете ассистенту «что мне писал Даниил в MAX?» или «сделай в группе опрос на завтра» — он читает и отправляет от вашего имени.

Сервер ставится на ваш VPS: сессии мессенджеров не уходят третьим лицам.

• 61 инструмент: 39 для Telegram, 22 для MAX

• работает с ChatGPT (веб и телефон), Claude, Claude Code, Cursor — через HTTP или stdio

• постоянное подключение к мессенджерам, без входа на каждый запрос (в наших замерах ~0,1 с на вызов)

• белые списки и лимит отправки, режим «только чтение», защита от инструкций в чужих сообщениях

• установка одной командой на Ubuntu/Debian или через Docker

Что умеет

Файлы можно передавать ссылкой или прикрепить прямо в чате ChatGPT — сервер объявляет параметры-файлы через openai/fileParams.

Related MCP server: mcp-telegram

Как это устроено

flowchart LR
  A[ChatGPT / Claude / Cursor] -- HTTPS + секретный путь --> N[nginx + Let's Encrypt]
  N --> S[tg-max-mcp<br/>127.0.0.1:8765]
  S -- MTProto, при блокировке через SOCKS/xray --> T[(Telegram)]
  S -- WebSocket --> M[(MAX)]

Инструменты чтения помечены readOnlyHint — ChatGPT вызывает их без подтверждения. Отправка, удаление и изменения помечены как запись: клиент спросит вас перед выполнением.

Установка на VPS

Нужно: Ubuntu 22.04+/Debian 12+, доменное имя или белый IP, открытые порты 80 и 443, ключи приложения Telegram с my.telegram.org → API development tools.

git clone https://github.com/minchiki/tg-max-mcp && cd tg-max-mcp
sudo bash deploy/install.sh          # пользователь tgmcp, /opt/tg-mcp, venv, systemd
sudo nano /etc/tg-mcp/env            # впишите TG_API_ID и TG_API_HASH

Если хостер блокирует Telegram (например, VPS в России), поднимите VPN только для сервера — подойдёт подписка с vless:// (reality/tls, tcp/ws/grpc/xhttp):

sudo bash deploy/setup-vpn.sh "https://ваша-подписка" "Финляндия"   # номер или часть названия сервера

Вход и запуск:

sudo bash deploy/login.sh            # QR → Telegram: Настройки › Устройства › Подключить устройство
sudo bash deploy/max_login.sh        # QR → приложение MAX (необязательно)
sudo systemctl enable --now tg-mcp
sudo bash deploy/setup-https.sh      # без аргумента — бесплатный адрес <ip>.sslip.io

Последняя команда напечатает адрес вида https://1-2-3-4.sslip.io/<секрет>/mcp. Это и есть ключ доступа к вашим перепискам — никому его не показывайте.

Обновление: git pull && sudo bash deploy/install.sh — настройки и сессии сохраняются.

Docker

cp deploy/env.example .env && nano .env      # TG_API_ID, TG_API_HASH, TG_SECRET=$(openssl rand -hex 24)
docker compose run --rm tg-mcp python login_qr.py
docker compose run --rm tg-mcp python max_login.py    # необязательно
docker compose up -d                                  # слушает 127.0.0.1:8765

HTTPS перед контейнером — ваш nginx, Caddy или Cloudflare Tunnel; проксируйте только путь /<TG_SECRET>/mcp.

Подключение

ChatGPT — Настройки › Plugins (Apps) › Add › Add custom MCP server: адрес сервера, Authentication — No authentication. В чате: @Имя плагина покажи мои чаты.

Claude.ai — Settings › Connectors › Add custom connector, адрес сервера.

Claude Code

claude mcp add --transport http telegram https://ваш-хост/<секрет>/mcp

Локально, без сервера (stdio) — для Claude Desktop, Claude Code, Cursor на своём компьютере:

pip install -r requirements.txt
cd app && TG_API_ID=... TG_API_HASH=... python login_qr.py
claude mcp add telegram -e TG_API_ID=... -e TG_API_HASH=... -- python /путь/к/app/server.py --stdio

Если ChatGPT пишет «Couldn't reach the MCP server»

Серверы OpenAI могут не достучаться до некоторых IP (в том числе российских хостеров). Помогает бесплатный ретранслятор на Vercel: впишите свой хост в relay/vercel.json и выполните npx vercel deploy --prod в папке relay. В ChatGPT указывайте https://<проект>.vercel.app/<секрет>/mcp.

Настройки — /etc/tg-mcp/env

После изменения: sudo systemctl restart tg-mcp. Журнал: journalctl -u tg-mcp -f — каждая отправка и удаление пишутся строкой TG SEND … / MAX DELETE ….

Безопасность

• Адрес сервера = доступ к аккаунтам. Секретный путь — единственная защита HTTP-режима; при утечке смените TG_SECRET и перезапустите сервис.

• Чужие сообщения — это данные, а не команды. Из текста, имён и кнопок вырезаются управляющие и невидимые символы, длина ограничена, а сервер сообщает клиенту в instructions, что выполнять просьбы из переписок нельзя. Полностью защититься от prompt injection это не гарантирует — для максимальной осторожности включите READ_ONLY=1.

• Отправка ограничена белыми списками и лимитом в минуту; по умолчанию разрешено только «Избранное» Telegram.

• Ссылки на файлы скачиваются только с публичных адресов (локальные и внутренние IP запрещены).

• Сервис работает от отдельного пользователя с ProtectSystem=strict; сессии лежат в /var/lib/tg-mcp с правами 700.

• В MAX не нажимайте «Выйти на всех устройствах» — сессия сервера пропадёт, понадобится повторный max_login.sh.

Ограничения и риски

• MAX подключается через неофициальный протокол web-клиента. После обновлений MAX что-то может сломаться до обновления PyMax; автоматизация личного аккаунта может нарушать правила сервиса.

• Telegram допускает userbot-клиенты, но за рассылки и спам аккаунт ограничивают. Не используйте сервер для массовых сообщений.

• Нет: звонков, историй, голосовых и управления ботами/каналами в MAX, нескольких аккаунтов.

Благодарности

• Telethon (MIT) и PyMax (MIT) — клиенты Telegram и MAX.

• MCP Python SDK (MIT).

• Набор инструментов Telegram сверялся с chigwell/telegram-mcp — если вам нужен только Telegram на своём компьютере и больше функций (несколько аккаунтов, ленты событий), посмотрите его.

Автор

Новости, обновления и другие проекты — в Telegram-канале HUICODING.

Лицензия

MIT