Your Telegram account, but it takes HTTP requests. Wraps Telethon, the real MTProto userbot clien...
6.6K
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.
The full documentation is at psyb0t.github.io/docker-telethon-plus.
| 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 |
+-------------------+ +-----------------------+
| 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.
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.
The skill works in any agent that reads .agents/skills/ (such as peen), and installs natively in the clients below.
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 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.
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).
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.
Content type
Image
Digest
sha256:7677b9074…
Size
66.9 MB
Last updated
9 days ago
docker pull psyb0t/telethon-plus