telethon-plus: Your Telegram Account as an HTTP API and MCP Server

Telegram has two APIs. The Bot API: neutered, restricted, limited to whatever Telegram decided bots are allowed to do. And MTProto: the actual protocol your phone uses, with full account access, no restrictions. Bots can’t read message history before they joined a chat. Bots can’t see who’s in a private group they’re not in. Bots can’t act as you. MTProto can.
Telethon is a Python MTProto client. telethon-plus wraps it in a Docker container with both an HTTP REST API and an MCP server. POST some JSON, or point an AI agent at /mcp/, and it talks to Telegram as you with full account access. One login. One session string. Never type a code again.

Userbot, Not a Bot

This is a userbot, not a bot. The distinction matters.
A bot is what BotFather gives you. Limited write access, no message history, no group membership without explicit invite, can’t react to most events. The Bot API is fine for sending notifications. It’s useless for anything that requires reading what’s actually happening in your chats.
A userbot is your account, controlled programmatically. Same access you have when you open Telegram on your phone. Read every message in every chat you’re in. Send messages as yourself. Forward, delete, edit. Join groups. Create channels. Act with your real identity, full history, full visibility.
The downside: it’s your account. If you abuse it, your account gets banned. Telegram rate-limits aggressively (FloodWaitError). Don’t spam. Use it for what it’s for: programmatic access to your Telegram, not mass messaging.

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..."
      TELETHON_AUTH_KEY: "your-bearer-token"
    restart: unless-stopped

Get API_ID and API_HASH from my.telegram.org/apps. Get the session string from the login helper.

First-Time Login

Telegram makes you prove you’re human once: phone number, SMS code, optionally 2FA. The container has an interactive login mode that walks you through it and spits out a session string at the end:

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

Or if you’ve cloned the repo: cp .env.example .env, fill in TELETHON_API_ID and TELETHON_API_HASH, then make login: it builds the image, runs the flow, and writes TELETHON_SESSION straight into your .env.
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.

The Tools

Same tool registry, two surfaces. Every tool works as both a REST endpoint and an MCP tool: JSON in, JSON out, schema-validated by pydantic. Send garbage, get a 400 back with exactly what’s wrong.

  • get_me: return the authorized account profile
  • get_entity: resolve a username/ID/link to a full profile
  • send_message: send a text message (Markdown/HTML, reply, silent, link preview)
  • get_messages: read recent messages from a chat (newest first, search, pagination)
  • get_dialogs: list your chats, groups, and channels
  • forward_messages: forward messages between chats
  • delete_messages: delete messages by ID (revoke for everyone or just yourself)
  • edit_message: edit a message you sent
  • mark_read: mark messages in a chat as read
  • send_file: download a file from an HTTPS URL and send it to a chat
  • get_participants: list members of a group or channel
  • create_group: create a new supergroup or broadcast channel
  • delete_chat: delete a supergroup or channel you own
  • join_chat: join a public channel or supergroup
  • leave_chat: leave a channel or supergroup
  • get_message: fetch a single message by ID
  • download_media: pull a message’s media back as base64
  • bulk_resolve: resolve many usernames/IDs in one call instead of N round-trips
  • set_reaction / remove_reaction: react to messages
  • pin_message / unpin_message: pin management
  • create_poll, vote_poll, get_poll_results: polls end to end
  • promote_user, demote_user, ban_user, unban_user, kick_user: channel admin
  • join_via_invite: join through a private invite link
  • get_linked_chat: the discussion group behind a channel, or vice versa
  • account_health: how hard Telegram has been flood-waiting you lately, boiled down to ok, warning or high
  • throttle_status: what the rate limiter currently thinks

Thirty-four tools total, and every one of them is on both surfaces. The one that behaves differently is download_media: MCP hands you base64, REST streams the raw bytes with a proper Content-Type.
Chat references accept whatever Telethon accepts: @username, phone numbers, t.me/... links, numeric IDs as strings, supergroup/channel IDs (negative numbers like -1001234567890), or me for your own Saved Messages.

HTTP API

Standard REST. /api/me, /api/messages, /api/dialogs, etc. As of v0.4.0 a 2xx returns the resource directly: the old {"result": ...} envelope is gone. If you wrote a client against v0.3.x, unwrap one level less.

# who am I
curl https://ciprian.51k.eu80/api/me \
  -H "Authorization: Bearer $TELETHON_AUTH_KEY"
# send a message with Markdown
curl -X POST https://ciprian.51k.eu80/api/messages \
  -H "Authorization: Bearer $TELETHON_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat": "@somebody", "text": "**hello** from a container", "parse_mode": "md"}'
# read recent messages with full-text search
curl "https://ciprian.51k.eu80/api/messages?chat=me&limit=5&search=hello" \
  -H "Authorization: Bearer $TELETHON_AUTH_KEY"
# send a file from an HTTPS URL — never touches your disk
# (v0.4.0 folded /api/files into /api/messages; `caption` is now `text`)
curl -X POST https://ciprian.51k.eu80/api/messages \
  -H "Authorization: Bearer $TELETHON_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat": "@psyb0t", "file_url": "https://example.com/photo.jpg", "text": "look at this"}'

Photos now go out as photos, videos as playable videos with dimensions and duration, and audio with duration, title and artist when metadata exists. Documents retain the URL’s filename. force_document: true deliberately sends a document. The old extensionless upload bug is fixed; a failed or empty download is refused before anything gets sent.
Validation is strict: pydantic schemas reject extra fields and bad types with 400 and a detailed error body. Telegram RPC errors come back as 502 with the error class and message preserved, except flood waits that the client cannot sleep through, which return 429.
Health check at /healthz always public, no auth required. Returns {"status": "ok", "authorized": true}, and don’t read much into that flag. A bad or unauthorized session string stops the service from starting at all, and once it’s up the flag only says a client object exists, so it stays true even if the session gets revoked or Telegram drops off the network later.

MCP Server

Mounted at /mcp/ using the streamable HTTP transport. Every tool from the list above shows up automatically as an MCP tool with the same name and schema. Stateless: every request is independent, no session juggling.

http://your-host:8080/mcp/

Drop it into Claude Desktop, a custom agent, an LLM gateway, anything that speaks MCP over streamable HTTP. Works out of the box.
This is the part that matters. Any function-calling model can now read your Telegram, write to it, manage groups, forward content. The model decides when. The agent acts. Want Claude to summarize the last 50 messages from a chat into a daily digest? Plug in the MCP endpoint, ask. Want a model to forward customer support questions from a public channel to your team chat? Same. Want an agent that monitors a group for mentions and replies on your behalf? Done.

Not Getting Your Account Banned

This is the part that matters when you point automation at your own Telegram account: Telegram notices. Hammer the API and you get FLOOD_WAIT, then restrictions, then a dead account.
So there’s a real rate limiter now. Per-method token buckets, per-chat send and read intervals, and adaptive backoff when Telegram does return a FLOOD_WAIT. The defaults are sized to sit well under Telegram’s observed soft limits without you tuning anything. throttle_status tells you where you stand; account_health turns the recent FLOOD_WAITs into an ok, warning or high risk level.
Two safety switches for when you’re wiring something new: TELETHON_READ_ONLY refuses every mutating call, and TELETHON_DRY_RUN goes through the motions without actually sending. Point an LLM at your account for the first time with one of those on.
Entity cache. Resolving a username costs a real API call, and repeatedly resolving the same one is how you burn your quota for nothing. The cache persists across container restarts, so repeat lookups become free hits. v0.4.1 fixed a nasty bug in that path: the refresh was calling get_entity with a bare int, which Telethon treats as a PeerUser, so cached channels and groups raised, invalidated, and burned a ResolveUsername slot each time. Exactly the operation the cache existed to avoid. It wraps the correct Peer type now.
The restart path needed another fix: the persistent cache now keeps Telegram’s access hash, not just an ID, and clears itself when the session belongs to another account. Numeric chat IDs resolve through that cache, Telethon and then the account’s dialogs. Concurrent calls reserve their rate-limit slots before waiting, so ten simultaneous requests do not all squeeze through the same opening. Poll operations and timed bans also use Telegram’s current types and real expiry times rather than accidentally asking for a permanent ban.

Observability

/metrics exposes Prometheus format. /ws/updates streams incoming events as NewMessage, MessageEdited, MessageDeleted or ChatAction. The server’s own sends, edits and deletes are not echoed there or to the webhook. Set TELETHON_POST_TO_URL for outbound webhooks. A slow WebSocket consumer whose buffer fills is closed with 1013; reconnect and catch up with GET /api/messages instead of assuming no news means no messages.
The isolated unit suite runs without touching Telegram (make test-unit) and enforces a 93% coverage floor. Integration tests separately drive the real container against an account. These are different checks, not a mock pretending that Telegram accepted a message.

Skill and Plugin

The repo ships an agent skill plus an OpenClaw plugin under .agents/, published to ClawHub by CI on tag pushes. An agent installs it and knows the whole tool surface without you pasting the list into a prompt.

Auth

Set TELETHON_AUTH_KEY to enable Bearer token auth on every endpoint except /healthz and /metrics. The /ws/updates websocket takes the same key as a ?token= query parameter instead of a header. If you don’t set it, the API runs unauthenticated: fine for localhost, suicidal exposed to a network. Always set it.

Authorization: Bearer your-secret-key

The session string is the real secret: losing it means losing your account. Don’t even put it in compose YAML committed to a repo. .env file, gitignored, sourced at runtime.
Upgrade to v0.7.3 or newer before keeping or shipping access logs. Earlier uvicorn logs printed the WebSocket’s query token, including on rejected connections. The new release redacts it in both log formats; it cannot erase old logs. Rotate TELETHON_AUTH_KEY if those logs were retained or shared. The session string is a different credential and still needs its own protection.

Configuration

Everything via environment variables.

  • TELETHON_API_ID, TELETHON_API_HASH, TELETHON_SESSION: required, from my.telegram.org and the login helper
  • TELETHON_AUTH_KEY: Bearer token for REST + MCP. Empty = no auth. Set this.
  • TELETHON_HTTP_LISTEN_ADDRESS: default 0.0.0.0:8080
  • TELETHON_REQUEST_TIMEOUT: sounds like a per-request timeout, but it’s handed to Telethon as its connection timeout, which Telethon’s own docs say is not the timeout for requests (default 60 seconds)
  • TELETHON_FLOOD_SLEEP_THRESHOLD: auto-sleep through FloodWait errors below this many seconds (default 60). The safety valve.
  • TELETHON_DEVICE_MODEL, TELETHON_SYSTEM_VERSION, TELETHON_APP_VERSION: what Telegram thinks your client is
  • TELETHON_DOWNLOAD_DIR: scratch directory for uploads. Each upload gets a private temporary file, removed on success or failure; the default is /tmp/telethon-plus.
  • TELETHON_PROXY: optional socks5://, socks4:// or http:// proxy as scheme://[user:password@]host:port. Both the server and login helper use it. Invalid values stop startup.

The flood sleep threshold decides which Telegram waits the client sleeps through. Longer waits return HTTP 429 with Retry-After and seconds, or an MCP flood_wait error. Other Telegram RPC refusals remain 502 / telegram_rpc. MCP refusals now set isError: true, so an agent is not told a rejected operation succeeded.

Tests Hit Real Telegram

The live suite runs the container against your actual account, with messages sent and deleted in a chat you specify (TEST_CHAT: use me for Saved Messages so nobody else sees the noise). Run the isolated unit suite when you do not want any Telegram effects.

cp .env.example .env
$EDITOR .env  # TELETHON_API_ID, TELETHON_API_HASH, TELETHON_SESSION, TEST_CHAT
make test

Tests cover validation errors, send-edit-fetch-delete roundtrips, dialog listing, entity resolution, public channel reads, group create-and-delete, participant lists, MCP tool discovery and invocation, auth middleware (401 on missing/wrong tokens, healthz always public). If credentials aren’t set, the suite skips cleanly.

Security

The session string equals your account. Treat it like a credit card number that’s also your photo ID. Specifically:

  • Always set TELETHON_AUTH_KEY: never run unauthenticated except on isolated localhost
  • Never commit TELETHON_SESSION to git: .env file, gitignored
  • If you suspect leakage, log into Telegram on your phone and revoke active sessions immediately
  • Don’t expose port 8080 to the public internet: put it behind a reverse proxy with TLS, or a Cloudflare Tunnel
  • Rotate the auth key if anything ever leaks

The container uses Python 3.14, Telethon, FastAPI and the MCP SDK. /healthz and /metrics are the only public endpoints, so disable the second with TELETHON_METRICS_ENABLED=false if nothing scrapes it. Everything else needs the bearer token when TELETHON_AUTH_KEY is set.

Plugged Into aigate

This is wired into aigate as one of its MCP servers. Flip TELETHON=1 in the aigate .env, set the credentials, and any function-calling model running through the gateway can now talk to your Telegram. Groq calls a tool, the tool hits Telegram, you get a message. The model decides when.
A free-tier Groq model that searches the web, scrapes a page, generates an image, and sends the result to your Saved Messages: zero tokens paid, one conversation, multiple tool calls. That’s the point.

The Bottom Line

Bot API is fine if you only need to send notifications. Userbots are what you want when you actually need to do things on Telegram: read messages, manage groups, act as yourself programmatically. telethon-plus puts a real MTProto client behind HTTP and MCP, so any tool that speaks JSON or any MCP-aware agent can drive your account.
Go grab it: github.com/psyb0t/docker-telethon-plus
The project is now GPL-2.0-or-later. Its image includes GPL-v2-only hachoir for media metadata, so distributing the combined image requires following GPL v2. This is no longer a WTFPL image you can redistribute without those obligations.

Installing It Into Your Agent

The telethon-plus manual has the full login and first-run instructions, tool catalog, HTTP and MCP references, update streams and throttling rules. Read the throttling page before making your actual Telegram account perform a thousand enthusiastic mistakes a minute.
The skill installs into Claude Code and Codex directly now. Everything under .agents/ is catalogued in one marketplace, so it is two commands:

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

Codex uses the same marketplace with a different verb: codex plugin add telethon-plus@psyb0t, because there is no codex plugin install. It also finds the skill on its own in a checkout of the repo, since it scans .agents/skills/ natively with nothing installed at all. It is also listed on the official MCP Registry now, so a client that resolves servers from there can find it without being handed a URL.

Get docker-telethon-plus on GitHub. Read the documentation for setup and usage.