Telethon Plus MCP server

docker-telethon-plus

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

• How it works
• Quick start
• First-time login
• Configuration
• Tools
• HTTP API
• MCP
• Agent integrations
• Development
• Tests
• License

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 — no duplication, no weird state, no bullshit.

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-helper..."
    restart: unless-stopped

Get APIID / APIHASH from . Get the session string from the login helper below.

First-time login

Telegram makes you prove you're a human once — phone number, SMS code, optionally 2FA. Do it once, never again.

cp .env.example .env
$EDITOR .env  # put in TELETHON_API_ID and TELETHON_API_HASH

make login

make login builds the image, runs the interactive flow, and shoves TELETHON_SESSION straight into your .env. That's it. Run make run and you're live.

No repo? No problem:

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

Copy the session string it spits out, set it as TELETHON_SESSION, done.

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.

Configuration

All config via environment variables. Copy .env.example to get the full list with comments.

Shortened. The full README is on GitHub.