Better Telegram

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.

CI codecov PyPI Docker License: MIT

Python Telegram MCP semantic-release Renovate

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-email-mcp	IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g...	MCP
better-notion-mcp	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
claude-plugins	Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...	Marketplace
imagine-mcp	Image and video understanding + generation for AI agents -- across Gemini, Op...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Shared foundation for building MCP servers -- Streamable HTTP transport, OAut...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
tacet	TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn...	Tooling
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP server for AI agents: web search, content extraction, and lib...	MCP

Table of contents

• Features
• Status
• Install
• Configuration
• Documentation
• Tools
• Comparison
• Security
• Build from Source
• Trust Model
• License

Features

• Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
• 7 tools with 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 (no session strings, no CLI sign-in)
• 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

Two clean transports: stdio (default, bot mode) and HTTP (bot + user mode, browser relay setup, optional multi-user). No daemon-bridge layer and no auto-spawn from stdio. See Modes overview for the full transport model.

Sister MCP servers from the same author are listed in the collapsible section above -- they share this architecture, so install patterns transfer.

Install

# 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 bot mode only (TELEGRAM_BOT_TOKEN). User mode (full account via phone + OTP) runs in HTTP mode, where credentials are entered through the browser-based relay form at /authorize.

Full setup matrices live at the canonical docs site mcp.n24q02m.com/servers/better-telegram-mcp/setup/, and the paste-to-agent snippets at claude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.

Configuration

Settings load from TELEGRAM_-prefixed environment variables (Pydantic Settings).

Stdio mode (bot only):

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather (format 123456789:ABCdef...)

HTTP mode (bot + user): credentials are entered via the browser relay form, not env vars. Server-side env vars for self-hosting:

Variable	Required	Default	Description
MCP_TRANSPORT	Yes	stdio	Set to http to enable HTTP mode (--http CLI flag or TRANSPORT_MODE=http also work)
PUBLIC_URL	Self-host	--	Public URL of the server; presence enables the multi-user OAuth branch
MCP_DCR_SERVER_SECRET	Self-host	--	Multi-user OAuth shared secret, 32+ random bytes (legacy DCR_SERVER_SECRET still accepted)
HOST	No	0.0.0.0	Bind address
PORT	No	8080	HTTP port

User-mode credentials (optional overrides): TELEGRAM_API_ID and TELEGRAM_API_HASH ship with built-in public dev defaults, so only TELEGRAM_PHONE is needed to start the phone + OTP flow. TELEGRAM_SESSION_NAME and TELEGRAM_DATA_DIR customize the Telethon session file location. There is no TELEGRAM_PASSWORD env var -- 2FA is entered through the web UI and never stored in the environment.

Documentation

Full docs at mcp.n24q02m.com/servers/better-telegram-mcp/setup/:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio / local-relay / remote-relay / remote-oauth
• Multi-user setup -- per-JWT-sub credential model

Install with AI agent -- paste this to your AI coding agent:

Install MCP server better-telegram-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.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
config__open_relay	--	Re-trigger the zero-config relay setup flow (prints a fresh relay URL for the browser form). Registered via mcp-core's register_open_relay_tool so an LLM can restart setup without a manual restart

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

Comparison

How better-telegram-mcp stacks up against direct competitors in each pillar:

Capability	better-telegram-mcp	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Bot API mode (bot token)	Yes (httpx)	No	No	Yes
MTProto user-account mode	Yes (Telethon)	Yes	Yes	No
Send / edit / delete messages	Yes	Yes	No (read-only, draft only)	Yes (send only)
Media download from messages	Yes	Yes	Yes	No (send only)
Contact management (add / block)	Yes (user mode)	Yes	Partial (list only)	No
Web-based / browser OTP auth	Yes (relay form, headless)	No (CLI session string)	No (CLI sign-in)	No (pre-set bot token)
Multi-user remote, per-user isolation	Yes (per-JWT-sub backends)	No	No	No
SSRF protection	Yes (URL validation + DNS-rebinding)	?	?	No
Path-traversal prevention	Yes	Yes (real-path allowed-root)	?	No
Self-hostable	Yes	Yes	Yes	Yes

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 trust model 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	~/.config/mcp/config.enc (credentials) + ~/.better-telegram-mcp/<name>.session (Telethon session)	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

License

MIT -- See LICENSE.