docker-telethon-plus

Your Telegram account, but it takes HTTP requests. Wraps Telethon, the real MTProto userbot client and 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

• Documentation

• How it works

• Quick start

• Agent integrations

• License

Related MCP server: telegram-mcp

Documentation

The full documentation is at psyb0t.github.io/docker-telethon-plus.

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, so there is no duplication, no weird state, no bullshit. On top of that sits a flood guard (per-method buckets, per-chat gaps, adaptive backoff and an entity cache) that keeps the account under Telegram's limits; Throttling and cache has the details.

Quick start

Get API_ID / API_HASH from https://my.telegram.org/apps, then log in once. Telegram makes you prove you're a human once: phone number, login code, optionally 2FA. The login prints a session string:

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

Then run it with that string:

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

volumes:
  telethon-cache:

export TELETHON_AUTH_KEY=a-long-random-string  # the key from the compose file
curl -H "Authorization: Bearer $TELETHON_AUTH_KEY" http://127.0.0.1:8080/api/me

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. Without TELETHON_AUTH_KEY, anyone who reaches the port is you too. Read Security before exposing it.

From a checkout, make login writes the session string into .env and make run starts the container. Getting started has every step.

Agent integrations

The skill works in any agent that reads .agents/skills/ (such as peen), and installs natively in the clients below.

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install telethon-plus@psyb0t

Claude Code prompts for the telethon-plus server URL and, if auth is enabled, the bearer token, which it keeps in your OS keychain.

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add telethon-plus@psyb0t

Installed via the marketplace, the skill invokes as $telethon-plus:telethon-plus. Codex also picks the skill up automatically with no install in any repo containing .agents/skills/, where it invokes as plain $telethon-plus.

OpenClaw

The skill is published to ClawHub on every release:

openclaw skills install @psyb0t/telethon-plus

For MCP clients that speak local stdio, the @psyb0t/telethon-plus plugin bridges to the service's /mcp/ endpoint:

openclaw plugins install clawhub:@psyb0t/telethon-plus

Then set TELETHON_PLUS_URL (and TELETHON_AUTH_KEY if the server requires auth).

License

Copyright (C) 2026 Ciprian Mandache. Licensed under the GNU General Public License, version 2 or later. The image includes hachoir, which is GPL v2 only, so the image as a whole is distributed under GPL v2.