messageLABSCO SUMMARY
Both halves of Telegram behind one set of tools.
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.
What it is
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.
What you get
messagesends, edits, deletes, forwards, pins, reacts, searches and browses historychatlists and manages chats, groups and channels — members, admin actions and forum topicsmediasends photos, files, voice notes and video, and downloads media out of messagescontactlists, searches, adds and blocks contacts, in user modeconfigreports server status and runtime settings and drives credential setup;helpreturns the reference for any topicconfig__open_relayprints 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
Requirements
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.
Setup effort
One command — uvx better-telegram-mcp
USE CASES
01
Reading and answering a chat from your assistant
Browse history, search for the thread you mean, then send or edit a reply without opening the app.
02
Pulling files out of a busy channel
Find the message, download the attachment, and send back whatever you produce from it.
03
Running a bot's chat housekeeping
List members, apply admin actions and manage forum topics as a conversation instead of a dashboard.
04
Setting it up on a machine you are not sitting at
HTTP mode hands the phone, OTP and 2FA steps to a browser form, so no credential is typed into a config file.
7 tools
Listed in project docs. Your client may show a different list.
chatmediacontactconfighelpconfig__open_relayBEFORE YOU INSTALL
What to know first
Tools you get
7 tools named in the project's documentation.
Requires
uvx on PATH
Optional
TELEGRAM_BOT_TOKEN in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx better-telegram-mcpMCP Clients
Claude Code — plugin
CLAUDE CODE — PLUGIN · IN CLIENT
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-pluginsClaude Code — uvx
CLAUDE CODE — UVX · TERMINAL
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcpAny MCP client — Docker
ANY MCP CLIENT — DOCKER · TERMINAL
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcpAny MCP client — uvx
ANY MCP CLIENT — UVX · TERMINAL
uvx --python 3.13 better-telegram-mcp
