docker-telethon-plus

Your Telegram account, but it takes HTTP requests. Wraps Telethon — the real MTProto userbot client, not that neutered Bot API garbage — behind a JSON HTTP API and a Model Context Protocol endpoint.

Same tools, two doors. POST some JSON, or point your AI agent at /mcp and let it go nuts. Either way it's talking to Telegram as you, with full account access.

One login. One session string. Never type a code again.

Table of Contents

• How it works
• Quick start
• First-time login
• Configuration
• Tools
• HTTP API
• MCP
• Agent integrations
• Development
• Tests
• License

How it works

+-------------------+        +-----------------------+
|  Any HTTP client  | -----> |  REST  /api/...       | --+
+-------------------+        +-----------------------+   |
                                                         |   +-----------+        Telegram
+-------------------+        +-----------------------+   +-> |  Telethon | <----> Servers
|  MCP-aware agent  | -----> |  /mcp  (Streamable    | --+   +-----------+       (MTProto)
|  (Claude, etc.)   |        |   HTTP transport)     |
+-------------------+        +-----------------------+

One Telethon client. One async lock. Both surfaces share the same tool registry — no duplication, no weird state, no bullshit.

Quick start

services:
  telethon-plus:
    image: psyb0t/telethon-plus
    ports:
      - "8080:8080"
    environment:
      TELETHON_API_ID: "123456"
      TELETHON_API_HASH: "your-api-hash"
      TELETHON_SESSION: "1Aa...long-string-from-login-helper..."
    restart: unless-stopped

Get API_ID / API_HASH from https://my.telegram.org/apps. Get the session string from the login helper below.

First-time login

Telegram makes you prove you're a human once — phone number, SMS code, optionally 2FA. Do it once, never again.

cp .env.example .env
$EDITOR .env  # put in TELETHON_API_ID and TELETHON_API_HASH

make login

make login builds the image, runs the interactive flow, and shoves TELETHON_SESSION straight into your .env. That's it. Run make run and you're live.

No repo? No problem:

docker run --rm -it \
  -e TELETHON_API_ID=123456 \
  -e TELETHON_API_HASH=your-api-hash \
  psyb0t/telethon-plus login

Copy the session string it spits out, set it as TELETHON_SESSION, done.

The session string is full account access. Whoever has it is you. Don't commit it, don't paste it in Slack, don't tattoo it anywhere.

Configuration

All config via environment variables. Copy .env.example to get the full list with comments.

Throttling & cache (anti-flood)

Telegram bans accounts that hammer it. Defaults here are conservative — meant to keep you under the server-side limits without you having to think about it. Tune only if you know what you're doing.

How the layers stack:

1. Entity cache short-circuits resolveUsername — first lookup of @somechannel calls Telegram; every subsequent lookup is free. Survives container restarts via the /cache volume.
2. Per-method token buckets cap the dangerous methods. If you try to resolve 6 new usernames in one minute, the 6th sleeps until the oldest expires.
3. Per-chat send interval throttles sends to each chat to ≤1/sec (with margin).
4. Global gap + jitter humanizes the overall traffic shape.
5. Adaptive backoff: a single FLOOD_WAIT halves your effective rate for an hour. Three in a row → ÷8. Auto-recovers after an idle hour.

For bulk scraping work (the scenario that caused 22-hour bans before): the cache + bucket_resolve_per_min=5 combination is what saves you. Resolving 200 new channels takes ~40 minutes instead of getting you banned in 5.

Tools

JSON in, JSON out. All inputs are pydantic-validated — send garbage, get a 400 back with exactly what's wrong.

Chat references (chat, from_chat, to_chat) accept whatever Telethon accepts:

Numeric IDs only resolve for entities Telethon has already seen — i.e. cached in your session via a prior @username / t.me lookup, dialog list, or incoming message. MTProto needs an access_hash, not just an ID, and bare numbers don't carry one. Especially relevant for bots: pass @botusername first (or call GET /api/dialogs / GET /api/entities?chat=@bot once) before referring to it by numeric ID. If you only have the bot's token and no username, hit Telegram's Bot API getMe to fetch the username, then use that.

Response shape

Every 2xx returns the resource directly. No {"result": ...} wrapper, no envelope. Lists are JSON arrays, singles are JSON objects.

Errors return {"detail": "..."} (FastAPI standard). Telegram RPC errors arrive as 502 with detail = {"telegram_error": "...", "message": "..."}.

Quick reference