Most Telegram servers pick a side: a bot token, or a user session. This one carries both, and the tool surface stays the same either way, so a workflow written against `message` and `chat` keeps working when you switch. The sign-in is the part worth planning: stdio mode stores an encrypted config and a Telethon session on the machine that runs it, while HTTP mode collects phone, OTP and 2FA through a browser form.
A Telegram server with two modes on one codebase: the Bot API over httpx for bot tokens, and MTProto over Telethon for a real user account. It picks the mode from whichever credentials you supply.
- `message` sends, edits, deletes, forwards, pins, reacts, searches and browses history
- `chat` lists and manages chats, groups and channels — members, admin actions and forum topics
- `media` sends photos, files, voice notes and video, and downloads media out of messages
- `contact` lists, searches, adds and blocks contacts, in user mode
- `config` reports server status and runtime settings and drives credential setup; `help` returns the reference for any topic
- `config__open_relay` prints a fresh setup URL so sign-in can be restarted without restarting the server
- 7 tools in all, each declaring readOnlyHint, destructiveHint, idempotentHint and openWorldHint so a client knows what is safe to auto-approve
The PyPI package better-telegram-mcp, version 4.18.0-beta.6, run over stdio with `uvx --python 3.13`, or the Docker image n24q02m/better-telegram-mcp. Bot mode needs TELEGRAM_BOT_TOKEN from @BotFather. User mode needs a phone number — TELEGRAM_API_ID and TELEGRAM_API_HASH ship with public defaults. HTTP mode is opt-in with MCP_TRANSPORT=http plus PUBLIC_URL and MCP_DCR_SERVER_SECRET when self-hosting.
One command plus a key — uvx better-telegram-mcp, then supply credentials