Better Telegram MCP
mcp-name: io.github.n24q02m/better-telegram-mcp
MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot integrations and MTProto (Telethon) for full user-account access.
Features
- Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
- 6 tools with action dispatch:
message, chat, media, contact, config, help
- Auto-detect mode -- Set bot token for bot mode, or API credentials for user mode
- Web-based OTP auth -- Browser-based authentication with remote relay support for headless environments
- Tool annotations -- Each tool declares
readOnlyHint, destructiveHint, idempotentHint, openWorldHint
- MCP Resources -- Documentation available as
telegram://docs/* resources
- Security hardened -- SSRF protection, path traversal prevention, error sanitization
Status
2026-05-02 -- Architecture stabilization update
Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v<auto>, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.
Apologies for the instability period. If you encountered issues with prior versions, please update to v<auto>+ and follow the current docs/setup-manual.md -- most prior workarounds are no longer needed.
Related plugins from the same author:
All plugins share the same architecture -- install once, learn pattern transfers.
Setup
- Stdio mode (default) --
TELEGRAM_BOT_TOKEN env var, bot mode only. See setup-manual.md.
- HTTP mode (encouraged) -- bot mode + user mode (MTProto via phone+OTP), browser-based setup with bundled api_id/hash. See setup-manual.md.
With AI Agent -- copy and send this to your AI agent:
Please set up better-telegram-mcp for me. Follow this guide:
https://raw.githubusercontent.com/n24q02m/better-telegram-mcp/main/docs/setup-with-agent.md
Manual Setup -- follow docs/setup-manual.md
Tools