telethon-plus

Your Telegram account, but it takes HTTP requests. telethon-plus wraps Telethon, the real MTProto user client and not the Bot API, behind a JSON HTTP API and a Model Context Protocol endpoint, in one Docker image.

Same tools, two doors. POST some JSON, or point an AI agent at /mcp/ and let it work. Either way it talks to Telegram as you, with full account access, so read Security before you put it anywhere.

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

One Telethon client behind one lock. Both doors share one tool registry, so a tool takes the same parameters and does the same thing over REST and MCP.

Install

docker pull psyb0t/telethon-plus

The image runs on linux/amd64 and linux/arm64. You need a Telegram app ID and hash from https://my.telegram.org/apps and a session string from the one-time login. Getting started walks through both.

Where to go next

You want to	Read
Log in once and get the container answering	Getting started
Set an environment variable, a proxy or the port	Configuration
See every tool, its route and its parameters	Tools
Call the REST API: auth, responses, errors, examples	HTTP API
Hook up Claude, Codex or another agent	MCP and agents
Receive incoming messages live or by webhook	Updates and webhooks
Keep the account from getting rate-limited or banned	Throttling and cache
Watch metrics, flood state and health	Observability
Lock it down before exposing it	Security
Fix a startup error or a failing call	Troubleshooting
Change the code, run the tests, cut a release	Development