Better Telegram MCP

telegram

mcp-name: io.github.n24q02m/better-telegram-mcp

Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
agent-chat-plugin	Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor...	Tooling
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-drive	2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray	Tooling
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-semantic-release	Drop-in python-semantic-release fork with built-in release-safety guards (orp...	Tooling
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
better-workspace-mcp	Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	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	A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl...	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
• Smithery
• Configuration
• CLI
• 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
• Local CLI auth -- auth configures a single-user machine; login remains a deprecated alias
• 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

The executable defaults to stdio for local single-user operation. HTTP is opted into with --http, MCP_TRANSPORT=http, or TRANSPORT_MODE=http; HTTP is the deployment mode for browser relay setup and optional multi-user access. The canonical stack mode matrix names HTTP remote relay as the deployed Telegram default, so changing the executable default requires a separate transport-contract decision and migration. This repository does not silently claim those two defaults are already reconciled.

There are no daemon-bridge layers 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

# Local 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 n24q02m-telegram

# Method 2 (fallback): Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP
docker run -d --name telegram-http -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PUBLIC_URL=https://telegram.example.com \
  -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \
  n24q02m/telegram:latest

The package is n24q02m-telegram (formerly better-telegram-mcp; old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-telegram-mcp, the Docker image is now n24q02m/telegram, and the legacy better-telegram-mcp command is kept as an alias of telegram. Local data moves once from ~/.better-telegram-mcp to ~/.telegram on first start.

Install matrix

Client	Install
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-telegram-mcp@n24q02m-plugins (stdio bot mode), or claude mcp add as in the block above
Cursor / Windsurf / Gemini CLI / any MCP client	mcpServers JSON in the client's config — stdio command, or type: "http" + url pointing at a deployment

Full per-client walkthroughs: mcp.n24q02m.com/servers/better-telegram-mcp/setup/.

Stdio mode is local single-user mode. Bot mode uses TELEGRAM_BOT_TOKEN; user mode can be configured locally with telegram auth --phone <+number>. HTTP user mode uses the browser-based relay form at /authorize for 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 at https://<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.

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.

Smithery

Also listed on Smithery. Per smithery.yaml, Smithery starts the server over stdio with uvx --python 3.13 n24q02m-telegram and takes no install-time configuration (empty configSchema) -- credentials are provided at runtime through the server's own setup flow: the TELEGRAM_BOT_TOKEN env var or local auth command for stdio single-user mode, or the browser relay form for HTTP user mode (see Configuration).

Configuration

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

Stdio mode (local single-user):

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 -- HTTP relay 2FA is entered through the web UI; local CLI auth prompts interactively and never stores it in the environment.

CLI

The telegram console script (installed by uvx / pip; better-telegram-mcp server** when 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).

telegram            # start the MCP server (stdio, bot mode by default)
telegram --http     # start in HTTP mode
telegram --version  # print the version

Subcommands (telegram <subcommand>):

Subcommand	Usage	Description
auth	auth --bot-token <token> or auth --phone <+number>	Authenticate this machine (single-user). Bot mode validates the token; phone mode runs the interactive OTP/2FA flow and stores the Telethon session on disk
login	Same arguments as auth	Deprecated alias of auth
logout	logout	Revoke the Telegram session server-side, delete the local session file, and clear saved credentials
config	config status, config delete [--yes]	Show or delete the saved local credential config (env overrides still take precedence at server start)
relay	relay status, relay open, relay reset	Inspect, open (print a fresh setup URL for), or reset the browser relay setup session
doctor	doctor	Print environment diagnostics -- Python version, credential backend, config + relay state, and transport mode

# Bot mode: validate a bot token and save it to the local config
telegram auth --bot-token 123456:ABC-DEF

# User mode: interactive phone + OTP (+ 2FA if enabled) sign-in
telegram auth --phone +15551234567

# Remove local credentials and revoke the session
telegram logout

The auth command, its deprecated login alias, and logout are 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 the remote endpoint and Configuration).

Documentation

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

• 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 server telegram 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 telegram stacks up against direct competitors in each pillar:

Capability	telegram	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/telegram.git
cd telegram
uv sync
uv run telegram

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core trust model for full classification.

The project no longer operates an n24q02m-hosted Telegram endpoint. HTTP mode is available only on infrastructure an operator deploys and controls.

Mode	Storage	Encryption	Who can read your data?
HTTP self-host (opt-in)	In-memory dict[sub] = MTProtoSession	In-process only	Operator-controlled server process (cleared on restart)
stdio	~/.config/mcp/config.enc (credentials) + ~/.telegram/<name>.session (Telethon session)	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

Workspace username (HTTP setup form)

The browser setup form has an optional workspace username field. Entering the same username always lands you in the same per-sub bucket, so your session stays reachable across a re-authorization and across devices, instead of being tied to the one-off subject minted for each /authorize round-trip. Leaving it blank keeps the previous per-authorize behaviour.

Trust boundary: when the form is gated by a shared 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.

License

Apache-2.0 -- See LICENSE.