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:

• wet-mcp -- Web search + content extraction
• mnemo-mcp -- Persistent AI memory
• imagine-mcp -- Image/video understanding + generation
• better-notion-mcp -- Notion API
• better-email-mcp -- Email management
• better-telegram-mcp -- Telegram
• better-godot-mcp -- Godot Engine
• better-code-review-graph -- Code review knowledge graph

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

Tool	Actions	Description
message	send, edit, delete, forward, pin, react, search, history	Send, edit, delete, forward messages. Pin, react, search, browse history
chat	list, info, create, join, leave, members, admin, settings, topics	List and manage chats, groups, channels. Members, admin, forum topics
media	send_photo, send_file, send_voice, send_video, download	Send photos, files, voice notes, videos. Download media from messages
contact	list, search, add, block	List, search, add contacts. Block/unblock users (user mode only)
config	status, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete	Server status, runtime settings, cache, credential setup (relay, status, reset, complete)
help	--	Full documentation for any topic

MCP Resources

URI	Content
telegram://docs/messages	Message operations reference
telegram://docs/chats	Chat management reference
telegram://docs/media	Media send/download reference
telegram://docs/contacts	Contact management reference
telegram://stats	All documentation combined

Security

• 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

Build from Source

git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core/docs/TRUST-MODEL.md for full classification.

Mode	Storage	Encryption	Who can read your data?
HTTP n24q02m-hosted (default)	In-memory dict[sub] = MTProtoSession	In-process only	Server process (cleared on restart)
HTTP self-host	Same as hosted	Same	Only you (admin = user)
stdio proxy	~/.better-telegram-mcp/config.json	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

License

MIT -- See LICENSE.