better-telegram-mcp
About
Production-grade MCP server for Telegram with dual-mode Bot API + MTProto, 6 composite tools
Details
- Author
- n24q02m
- Categories
- Communication, Other, Productivity
Jump to
Setup
Install better-telegram-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/n24q02m/better-telegram-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Production-grade MCP server for Telegram with dual-mode Bot API + MTProto, 6 composite tools
mcp-name: io.github.n24q02m/better-telegram-mcp
Telegram for AI agents -- messages, chats, media, and contacts across both bot and full user-account modes.
- Features
- Status
- Install
- Smithery
- Configuration
- CLI
- Documentation
- Tools
- Comparison
- Security
- Build from Source
- Deploy to Cloudflare
- Trust Model
- License
- Dual mode-- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
- 7 toolswith action dispatch:message,chat,media,contact,config,help,config__open_relay
- Auto-detect mode-- Set bot token for bot mode, or API credentials for user mode
- Web-based OTP auth-- HTTP-mode browser relay form handles phone, OTP, and 2FA for user accounts
- Local CLI auth--authconfigures a single-user machine;loginremains a deprecated alias
- Tool annotations-- Each tool declaresreadOnlyHint,destructiveHint,idempotentHint,openWorldHint
- MCP Resources-- Documentation available astelegram://docs/resources
- Security hardened-- SSRF protection, path traversal prevention, error sanitization
Two clean transports:stdio(default, local single-user mode) andHTTP(bot + user mode, browser relay setup, optional multi-user). No daemon-bridge layer and no auto-spawn from stdio. SeeModes overviewfor the full transport model.
Sister MCP servers from the same author are listed in thecollapsible section above-- they share this architecture, so install patterns transfer.
# Method 1 (default): plugin install via Claude Code (stdio, bot mode) /plugin marketplace add n24q02m/claude-plugins /plugin install better-telegram-mcp@n24q02m-plugins # Method 1 (CLI): direct uvx invocation (stdio, bot mode) claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcp # Method 2 (fallback): Docker stdio docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp # Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP docker run -d --name better-telegram-mcp-http -p 8080:8080 \ -e MCP_TRANSPORT=http \ -e PUBLIC_URL=https://telegram.example.com \ -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \ n24q02m/better-telegram-mcp:latest
Stdio mode is local single-user mode. Bot mode usesTELEGRAM_BOT_TOKEN; user mode can be configured locally withbetter-telegram-mcp auth --phone <+number>. HTTP user mode uses the browser-based relay form at/authorizefor phone, OTP, and 2FA.
Remote endpoint-- an HTTP deployment is OAuth-gated and serves/mcp. Point any MCP client that speaks Streamable HTTP + OAuth 2.1 athttps://<your-host>/mcp; each user completes the browser relay setup (bot token, or phone + OTP) on first connect. To run one, use the Docker HTTP method above or theCloudflare deploybelow.
Full setup matrices live at the canonical docs sitemcp.n24q02m.com/servers/better-telegram-mcp/setup/, and the paste-to-agent snippets atclaude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.
Also listed onSmithery. Persmithery.yaml, Smithery starts the server overstdiowithuvx --python 3.13 better-telegram-mcpand takesno install-time configuration(emptyconfigSchema) -- credentials are provided at runtime through the server's own setup flow: theTELEGRAM_BOT_TOKENenv var or localauthcommand for stdio single-user mode, or the browser relay form for HTTP user mode (seeConfiguration).
Settings load fromTELEGRAM_-prefixed environment variables (Pydantic Settings).
HTTP mode (bot + user):credentials are entered via the browser relay form, not env vars. Server-side env vars for self-hosting:
User-mode credentials (optional overrides):TELEGRAM_API_IDandTELEGRAM_API_HASHship with built-in public dev defaults, so onlyTELEGRAM_PHONEis needed to start the phone + OTP flow.TELEGRAM_SESSION_NAMEandTELEGRAM_DATA_DIRcustomize the Telethon session file location. There is noTELEGRAM_PASSWORDenv var -- HTTP relay 2FA is entered through the web UI; local CLI auth prompts interactively and never stores it in the environment.
Thebetter-telegram-mcpconsole script (installed byuvx/pip)starts the serverwhen run with no subcommand, and exposes a few operator subcommands for local single-user setup and diagnostics. Any flag that is not a subcommand is passed straight through to the server (e.g.--http).
better-telegram-mcp # start the MCP server (stdio, bot mode by default) better-telegram-mcp --http # start in HTTP mode better-telegram-mcp --version # print the version
Subcommands(better-telegram-mcp <subcommand>):
# Bot mode: validate a bot token and save it to the local config better-telegram-mcp auth --bot-token 123456:ABC-DEF # User mode: interactive phone + OTP (+ 2FA if enabled) sign-in better-telegram-mcp auth --phone +15551234567 # Remove local credentials and revoke the session better-telegram-mcp logout
Theauthcommand, its deprecatedloginalias, andlogoutare single-user and local-machine only -- they write the on-disk Telethon session and the encrypted single-user config, so run them on the machine that hosts the stdio server. For remote / multi-user HTTP deployments, credentials are entered through the browser relay form instead (see theremote endpointandConfiguration).
Full docs atmcp.n24q02m.com/servers/better-telegram-mcp/setup/:
- Setup-- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Modes overview-- stdio (local, single-user) and HTTP (remote, OAuth 2.1)
- Multi-user setup-- per-JWT-sub credential model
Install with AI agent-- paste this to your AI coding agent:
Install MCP serverbetter-telegram-mcpfollowing the steps athttps://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md
How better-telegram-mcp stacks up against direct competitors in each pillar:
- SSRF Protection-- All URLs validated against internal/private IP ranges, DNS rebinding blocked
- Path Traversal Prevention-- File paths validated, sensitive directories blocked
- Session File Security-- 600 permissions, 2FA via web UI only (never stored in env vars)
- Error Sanitization-- Credentials never leaked in error messages
git clone https://github.com/n24q02m/better-telegram-mcp.git cd better-telegram-mcp uv sync uv run better-telegram-mcp
Run your own multi-user better-telegram-mcp serverless on Cloudflare (Worker + Container + KV).
Prerequisites:a Cloudflare account on theWorkers Paid plan-- required for Containers (the Cloudflare free tier does not include Containers) -- and thewranglerCLI.
- git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp
- wrangler login
- Provision the KV namespace and paste its id intowrangler.jsonc:
wrangler kv namespace create better-telegram-kv
docker pull ghcr.io/n24q02m/better-telegram-mcp:beta docker tag ghcr.io/n24q02m/better-telegram-mcp:beta better-telegram-mcp:beta wrangler containers push better-telegram-mcp:beta # prints registry.cloudflare.com/<ACCOUNT_ID>/better-telegram-mcp:beta
wrangler secret put CREDENTIAL_SECRET wrangler secret put MCP_RELAY_PASSWORD wrangler secret put MCP_DCR_SERVER_SECRET
Storage maps to Cloudflare viaMCP_STORAGE_BACKEND=cf-kv(the encrypted setup config). Do NOT setMCP_AUTH_DISABLEon a shared/public deployment -- it collapses all users into a single credential bucket.
This plugin implementsTC-NearZK(in-memory, ephemeral). Seemcp-core trust modelfor full classification.
The browser setup form has an optionalworkspace usernamefield. Entering the same username always lands you in the same per-subbucket, so your session stays reachable across a re-authorization and across devices, instead of being tied to the one-off subject minted for each/authorizeround-trip. Leaving it blank keeps the previous per-authorize behaviour.
Trust boundary: when the form is gated by ashared*MCP_RELAY_PASSWORD, the username is a partition key, not a secret -- anyone who knows that password can type any username and reach that bucket. That is fine for a trusted group; an untrusted multi-tenant deployment needs a per-user secret or delegated OAuth instead.
One-time migration:existing users must re-authenticate once after this change. Nothing is deleted; sessions stored under the old random subject are simply no longer addressed.
MCP server for Telegram bots built with aiogram. 30 tools, 7 resources, 3 prompts — messaging, rich media, moderation, interactive keyboards, real-time event streaming, rate limiting, permissions, and audit logging.
Build, edit, and deploy Telegram bots on FlowCastle's hosted visual flow platform.
Read-only public stats for Telegram groups tracked by Limzo — activity, engagement, mood and leaderboards, no API key required.
Telegram MCP server with 20 tools — read chats, search messages, download media via MTProto
A simple gateway to interact with Telegram bots using MCP and a REST API, enabling integration with LLMs.
MCTL for Telegram lets users access and manage their own Telegram account from ChatGPT after explicit user authorization. It supports reading recent chats, summarizing messages, drafting replies, preview-only sending by default, confirmed pin actions, audit review, and account disconnect/delete controls. It is not an official Telegram app or Telegram API partner, and Telegram message content is treated as untrusted user-generated data.
Manage your WhatsApp, SMS and Phone Calls using a single MCP connector
Connect to any function, any language, across network boundaries using AgentRPC.
Access your meeting transcripts, summaries, and action items from any AI assistant.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
