Better Telegram

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

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

Mode CI codecov PyPI Docker License: Apache-2.0

Python Telegram MCP semantic-release Renovate

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
• Install
• Setup
• Smithery
• Configuration
• HTTP mode
• CLI
• Tools
• Comparison
• Security
• Build from Source
• Trust Model
• License

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 a bot token for bot mode, or a phone number for user mode
• Local CLI auth -- telegram auth handles the bot token, or phone + OTP + 2FA, on the machine that runs the server
• Stdio or HTTP -- stdio by default; HTTP with no-auth (loopback only), a single bearer token, or per-user tokens
• 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, prompt-injection boundary tags on Telegram content

Install

# Claude Code plugin (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx n24q02m-telegram

# Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

The package is n24q02m-telegram (formerly better-telegram-mcp; the old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-telegram-mcp, the Docker image is 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 server you run (see HTTP mode)

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

Setup

Credentials are configured on the machine that runs the server.

Bot mode: set TELEGRAM_BOT_TOKEN in the client config, or save it once:

telegram auth --bot-token 123456:ABC-DEF

User mode: sign in interactively with your phone number. Telegram sends an OTP; a 2FA password is prompted if the account has one. The Telethon session is stored on disk.

telegram auth --phone +15551234567

Check the result with telegram status. The server reads saved credentials at startup, so restart it after telegram auth. Without any credentials the stdio server prints these instructions to stderr and exits with status 1.

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 come from the TELEGRAM_BOT_TOKEN env var or a prior telegram auth (see Setup).

Configuration

Settings load from TELEGRAM_-prefixed environment variables (Pydantic Settings). Env vars take precedence over credentials saved by telegram auth.

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Bot mode	Bot token from @BotFather (format 123456789:ABCdef...)
TELEGRAM_PHONE	User mode	Phone number in +<country><number> form
TELEGRAM_API_ID / TELEGRAM_API_HASH	No	Override the bundled public API pair
USE_BUNDLED_TELEGRAM_CLIENT	No	Set to false to require your own API pair
TELEGRAM_SESSION_NAME	No	Telethon session file name (default default)
TELEGRAM_DATA_DIR	No	Session directory (default ~/.telegram)
MCP_TRANSPORT	No	Set to http to start in HTTP mode (--http or TRANSPORT_MODE=http also work)

There is no TELEGRAM_PASSWORD env var: telegram auth prompts for the 2FA password and never stores it in the environment.

HTTP mode

telegram --http serves MCP at /mcp and an unauthenticated GET /health. Settings live in ~/.telegram/config.toml:

[server]
host = "127.0.0.1"   # default; --host overrides
port = 8000          # default; --port overrides
auth = "token"       # "no-auth" | "token" | "multi"
token_hash = "scrypt$..."

auth	Who can connect	Credentials used
no-auth	Anyone who can reach the port; loopback binds only (a non-loopback host is refused)	The default credentials
token	Clients sending Authorization: Bearer <token> matching token_hash	The default credentials
multi	Users listed in users.toml (default ~/.telegram/users.toml), each with their own token	Each user's own namespace

Create a token hash with telegram token hash (it reads the token from stdin or a prompt, never from the command line). In multi mode, add users by editing users.toml and restarting the server:

[users.alice]
token_hash = "scrypt$..."
enabled = true
namespace = "alice"

Then authorize Telegram for that user on the server machine:

telegram auth --phone +15551234567 --user alice

To reach a server on another machine, put it behind a TLS-terminating reverse proxy or a private network and use token or multi auth.

CLI

The telegram console script (installed by uvx / pip; better-telegram-mcp is a legacy alias) starts the MCP server when run without a subcommand. Flags that are not a subcommand are passed through to the server (for example --http, --host, --port).

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

Subcommand	Usage	Description
auth	auth --bot-token <token> or auth --phone <+number>, optional --user <ns>	Authorize this machine. 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 [--yes] [--user <ns>]	Revoke the Telegram session, delete the session file and the saved credentials
config	config status, config delete --yes	Show or delete the saved credential config
status	status	Show whether credentials are configured
doctor	doctor	Print environment diagnostics
token	token hash	Hash a bearer token for config.toml / users.toml

--user selects the storage namespace (default default, used by stdio and the no-auth / token HTTP modes). Unknown subcommands exit with status 2.

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	Server status, runtime settings (message_limit, timeout), cache
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

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
Multi-user HTTP, per-user isolation	Yes (per-user tokens and namespaces)	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; the 2FA password is prompted, never stored in env vars
• Error Sanitization -- Credentials and bot tokens are never leaked in error messages or logs
• Prompt-injection boundaries -- Telegram content returned by tools is wrapped in untrusted-content tags

Build from Source

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

Trust Model

The project does not operate a hosted Telegram endpoint. The server runs on infrastructure you control, and credentials never leave that machine.

Data	Location	Protection
Saved credentials (bot token / phone)	~/.telegram/config.json; ~/.telegram/subs/<ns>/config.json in multi mode	AES-256-GCM with the machine key ~/.telegram/.secret
Telethon sessions	~/.telegram/<name>.session; ~/.telegram/subs/<ns>/ in multi mode	File permission 0600
HTTP bearer tokens	token_hash in config.toml / users.toml	Stored only as scrypt hashes

Anyone with access to your OS user account can read these files.

License

Apache-2.0 -- See LICENSE.