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

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

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

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

Subcommands (better-telegram-mcp <subcommand>):

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

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

# Remove local credentials and revoke the session
better-telegram-mcp 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/:

• 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-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Tools

MCP Resources

Comparison

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

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

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.

1. git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp
2. wrangler login
3. Provision the KV namespace and paste its id into wrangler.jsonc:

   wrangler kv namespace create better-telegram-kv
   

4. Push the container image to your Cloudflare managed registry (CF Containers cannot pull from external registries directly), then set <YOUR_ACCOUNT_ID> in wrangler.jsonc:

   docker pull ghcr.io/n24q02m/better-telegram-mcp:beta
   docker tag ghcr.io/n24q02m/better-telegram-mcp:beta better-telegram-mcp:beta
   wrangler containers push better-telegram-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/better-telegram-mcp:beta
   

5. Set <YOUR_PUBLIC_URL> (e.g. https://telegram.example.com) and <YOUR_WORKER_DOMAIN> (e.g. telegram.example.com) in wrangler.jsonc, then set secrets:

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put MCP_DCR_SERVER_SECRET
   

   CREDENTIAL_SECRET is REQUIRED: it derives a deterministic OAuth signing key so user identity survives container recreation. MCP_RELAY_PASSWORD gates the browser setup form (Gate A shared front door); MCP_DCR_SERVER_SECRET (32+ random bytes) marks the deploy as intentionally multi-user.
6. 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.

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.