HUB
Sign inSign up

psyb0t/telethon-plus

By psyb0t

•Updated 9 days ago

Your Telegram account, but it takes HTTP requests. Wraps Telethon, the real MTProto userbot clien...

Image
0

6.6K

psyb0t/telethon-plus repository overview

Source⁠ | Project page⁠

⁠docker-telethon-plus

CI version license Docker Pulls

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

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

You want toRead
Log in once and get the container answeringGetting started⁠
Set an environment variable, a proxy or the portConfiguration⁠
See every tool, its route and its parametersTools⁠
Call the REST API: auth, responses, errors, examplesHTTP API⁠
Hook up Claude, Codex or another agentMCP and agents⁠
Receive incoming messages live or by webhookUpdates and webhooks⁠
Keep the account from getting rate-limited or bannedThrottling and cache⁠
Watch metrics, flood state and healthObservability⁠
Lock it down before exposing itSecurity⁠
Fix a startup error or a failing callTroubleshooting⁠
Change the code, run the tests, cut a releaseDevelopment⁠

⁠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).

⁠Sponsor

Buy Me a Coffee

⁠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.

Tag summary

Content type

Image

Digest

sha256:7677b9074…

Size

66.9 MB

Last updated

9 days ago

docker pull psyb0t/telethon-plus