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.

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 -- 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

Two clean transports: stdio (default, local single-user 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 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):

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