The Ultimate Telegram MTProto Proxy Manager

Interactive TUI · Full CLI · Telegram Bot · Per-user Access Control

Quick Start • Features • Comparison • Telegram Bot • CLI Reference • Changelog

MTProxyMaxPy is a full-featured Telegram MTProto proxy manager powered by the telemt 3.x Rust engine. It wraps the raw proxy engine with an interactive TUI, a complete CLI, a Telegram bot for remote management, per-user access control, traffic monitoring, and proxy chaining — all as a clean Python application.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/xoste49/MTProxyMaxPy/main/install.sh)"

Most MTProxy tools give you a proxy and a link. That is it. MTProxyMaxPy gives you a full management platform:

• Multi-user secrets with individual bandwidth quotas, device limits, and expiry dates
• Telegram bot — manage everything from your phone
• Interactive TUI — no need to memorize commands, menu-driven setup
• Real-time traffic stats — real per-user data from the engine
• Proxy chaining — route through SOCKS5 upstreams for extra privacy
• Auto-recovery — detects downtime, restarts automatically, alerts you on Telegram
• Pure Python — no Docker, no Bash, easy to extend

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/xoste49/MTProxyMaxPy/main/install.sh)"

The interactive wizard walks you through everything: port, domain, first user secret, and optional Telegram bot setup.

curl -fsSL https://raw.githubusercontent.com/xoste49/MTProxyMaxPy/main/install.sh -o install.sh
sudo bash install.sh

mtproxymaxpy           # Open interactive TUI
mtproxymaxpy status    # Check proxy health

Proxy traffic is indistinguishable from normal HTTPS. The telemt engine mirrors real TLS 1.3 sessions — per-domain profiles, real cipher suites, dynamic certificate lengths, and realistic record fragmentation. The SNI points to a cover domain (e.g. cloudflare.com), so DPI sees ordinary web browsing.

Traffic masking — when a non-Telegram client probes the server, the connection is forwarded to the real cover domain and responds exactly as it would.

Each user gets their own secret key with a human-readable label:

• Add/remove users instantly — config regenerates and proxy hot-reloads
• Enable/disable access without deleting the key
• Rotate a user's secret — new key, same label, old link stops working
• QR codes — scannable directly in Telegram

Fine-grained limits enforced at the engine level:

mtproxymaxpy secret add alice
mtproxymaxpy secret list
mtproxymaxpy secret rotate alice
mtproxymaxpy secret remove alice

Full proxy management from your phone. Supports /status, /users, /restart and sends automatic alerts:

• Proxy down: instant notification + auto-restart attempt
• Proxy recovered: notification with connection details
• Periodic traffic reports at your chosen interval

mtproxymaxpy telegram-bot          # Run bot (used by systemd)

Configure via TUI (Settings screen) or edit settings.toml directly.

Route traffic through intermediate servers:

mtproxymaxpy upstream add warp socks5 127.0.0.1:40000 --weight 20
mtproxymaxpy upstream add backup socks5 203.0.113.50:1080 --user user --password pass
mtproxymaxpy upstream list
mtproxymaxpy upstream remove warp

Supports SOCKS5 (with auth), SOCKS4, and direct routing with weight-based load balancing.

mtproxymaxpy status    # Overview with connection count and uptime

Per-user traffic data is read directly from the telemt engine stats.

Telegram Client
      |
      v
+-------------------------+
|  Your Server (port 443) |
|  +-------------------+  |
|  |  telemt binary    |  |  <- Rust/Tokio engine (native)
|  |  (FakeTLS v2)     |  |
|  +------+------------+  |
|         |               |
|  +------+------+        |
|  v             v        |
|  Direct    SOCKS5       |  <- Upstream routing
+-------------------------+
          |
          v
   Telegram Servers

mtproxymaxpy install              # Download telemt binary and run setup wizard
mtproxymaxpy start                # Start proxy
mtproxymaxpy stop                 # Stop proxy
mtproxymaxpy restart              # Restart proxy
mtproxymaxpy status               # Show proxy status
mtproxymaxpy update               # Download latest telemt binary and restart
mtproxymaxpy version              # Print version

mtproxymaxpy secret add <label>           # Add user
mtproxymaxpy secret remove <label>        # Remove user
mtproxymaxpy secret list                  # List all users
mtproxymaxpy secret rotate <label>        # New key, same label

mtproxymaxpy upstream add <name> <type> <host:port> [--user U] [--password P] [--weight W]
mtproxymaxpy upstream list
mtproxymaxpy upstream remove <name>

mtproxymaxpy telegram-bot         # Run bot process (blocking, for systemd)

Bot token and chat ID are configured via TUI (Settings screen) or directly in settings.toml.

All files are stored under /opt/mtproxymaxpy/ with mode 600.

If you were running the bash version of MTProxyMax, the first launch automatically detects settings.conf, secrets.conf, upstreams.conf, and instances.conf in /opt/mtproxymaxpy/ and offers an interactive migration wizard to import them.

To validate Linux-specific behavior (for example file permission checks), run tests in the dedicated Debian 13 test container:

make test

Equivalent direct command:

docker compose run --rm test

This command works the same on Linux/macOS/Windows and runs pytest with coverage inside Debian 13 (debian:trixie-slim).

This project uses pre-commit for lightweight checks and Ruff lint/format hooks.

uv run pre-commit install
uv run pre-commit run --all-files

Run lint checks:

uv run ruff check .
uv run ruff check . --fix

Run formatter:

uv run ruff format .
uv run ruff format --check .

Complete rewrite from Bash to Python 3.13:

• Replaced Bash + Docker stack with a native Python application managed by uv
• Textual TUI — fully interactive menu-driven interface
• Pydantic models — all config validated at load time, stored as TOML + JSON
• Native telemt binary — no Docker required; binary downloaded from GitHub releases
• aiogram — Telegram bot backend with command parity
• Typer CLI — install, start, stop, restart, status, update, secret, upstream
• Legacy migration — auto-detects old bash configs on first run and offers import
• Removed: replication (master-slave sync), Docker, iptables geo-blocking

Built on top of telemt — a high-performance MTProto proxy engine written in Rust/Tokio. All proxy protocol handling, FakeTLS, traffic masking, and per-user enforcement is powered by telemt.

MIT License — see LICENSE for details.

The telemt engine binary is licensed under the Telemt Public License 3 (TPL-3).

Copyright (c) 2026 xoste49