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)

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= \
  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 `. 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:///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 `):

# 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 `` 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//better-telegram-mcp:beta

5. Set `` (e.g. `https://telegram.example.com`) and ``

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