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

Install matrix

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

Deployment (CD-managed)

Managed deployments go through CI, never by hand: the deploy-cf job in
.github/workflows/cd.yml runs after a release,
checks out the released tag, builds the immutable http image at the released
version, pushes it to the Cloudflare managed registry, deploys, and gates on a
canary check — a managed instance can therefore only ever run an exact release
tag. Manual wrangler deploy against a managed/operated instance is not
permitted: it breaks the release-tag ↔ live-image correspondence, and the next
CD run would overwrite it.

The job is gated by the CF_HOSTED_ENABLED repository Actions variable —
currently false, so releases do not publish a hosted endpoint (per the
Trust Model, there is no operator-hosted public Telegram
endpoint). To run your own instance, use the self-host steps below.

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.