Better Telegram MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Better Telegram MCP listing page.
Better Telegram MCP
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
- Deploy to Cloudflare
- 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 --
authconfigures a single-user machine;loginremains 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
Stdio mode is local single-user mode. Bot mode uses TELEGRAM_BOT_TOKEN; user mode
can be configured locally with better-telegram-mcp 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 or the
Cloudflare deploy below.
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 better-telegram-mcp 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 better-telegram-mcp console script (installed by uvx / pip) starts the
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).
Subcommands (better-telegram-mcp <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 |
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/:
- 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
better-telegram-mcpfollowing 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
Deploy to Cloudflare
Run your own multi-user better-telegram-mcp serverless on Cloudflare (Worker + Container + KV).
Prerequisites: a Cloudflare account on the Workers Paid plan -- required for Containers (the Cloudflare free tier does not include Containers) -- and the wrangler CLI.
git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcpwrangler login- Provision the KV namespace and paste its id into
wrangler.jsonc: - Push the container image to your Cloudflare managed registry (CF Containers cannot
pull from external registries directly), then set
<YOUR_ACCOUNT_ID>inwrangler.jsonc: - Set
<YOUR_PUBLIC_URL>(e.g.https://telegram.example.com) and<YOUR_WORKER_DOMAIN>(e.g.telegram.example.com) inwrangler.jsonc, then set secrets:CREDENTIAL_SECRETis REQUIRED: it derives a deterministic OAuth signing key so user identity survives container recreation.MCP_RELAY_PASSWORDgates the browser setup form (Gate A shared front door);MCP_DCR_SERVER_SECRET(32+ random bytes) marks the deploy as intentionally multi-user. wrangler deploy, then complete setup in the browser relay form at your Worker domain -- each user enters their own bot token or phone + OTP there, so no per-user Telegram credentials live on the Worker.
Storage maps to Cloudflare via MCP_STORAGE_BACKEND=cf-kv (the encrypted setup config).
Do NOT set MCP_AUTH_DISABLE on a shared/public deployment -- it collapses all users
into a single credential bucket.
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) + ~/.better-telegram-mcp/<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.