telegram

telegram

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
• 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 isopted into with --http, MCP_TRANSPORT=http, or TRANSPORT_MODE=http; HTTPis the deployment mode for browser relay setup and optional multi-user access.The canonical stack mode matrix names HTTP remote relay as the deployedTelegram default, so changing the executable default requires a separatetransport-contract decision and migration. This repository does not silentlyclaim those two defaults are already reconciled.

There are no daemon-bridge layers and no auto-spawn from stdio. See Modesoverview for the fulltransport model.

Sister MCP servers from the same author are listed in the collapsible sectionabove -- they share this architecture, so installpatterns 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 n24q02m-telegram

# Method 2 (fallback): Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP
docker run -d --name telegram-http -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PUBLIC_URL=https://telegram.example.com \
  -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \
  n24q02m/telegram:latest

The package is n24q02m-telegram (formerly better-telegram-mcp; old packagereceives one final release then freezes). The MCP Registry id staysio.github.n24q02m/better-telegram-mcp, the Docker image is nown24q02m/telegram, and the legacy better-telegram-mcp command is kept as analias of telegram. Local data moves once from ~/.better-telegram-mcp to~/.telegram on first start.

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 modecan be configured locally with telegram auth --phone <+number>. HTTPuser 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 anyMCP client that speaks Streamable HTTP + OAuth 2.1 at https://<your-host>/mcp; eachuser completes the browser relay setup (bot token, or phone + OTP) on first connect.To run one, use the Docker HTTP method above.

Full setup matrices live at the canonical docs sitemcp.n24q02m.com/servers/better-telegram-mcp/setup/,and the paste-to-agent snippets atclaude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.

Smithery

Also listed on Smithery.Per smithery.yaml, Smithery starts the server over stdio withuvx --python 3.13 n24q02m-telegram and takes no install-time configuration(empty configSchema) -- credentials are provided at runtime through the server's ownsetup flow: the TELEGRAM_BOT_TOKEN env var or local auth command for stdiosingle-user mode, or the browser relay form for HTTP user mode (seeConfiguration).

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 andTELEGRAM_API_HASH ship with built-in public dev defaults, so onlyTELEGRAM_PHONE is needed to start the phone + OTP flow. TELEGRAM_SESSION_NAMEand TELEGRAM_DATA_DIR customize the Telethon session file location. There is noTELEGRAM_PASSWORD env var -- HTTP relay 2FA is entered through the web UI; localCLI auth prompts interactively and never stores it in the environment.

CLI

The telegram console script (installed by uvx / pip; better-telegram-mcpserver** when run with no subcommand, and exposes a few operator subcommands for localsingle-user setup and diagnostics. Any flag that is not a subcommand is passed straightthrough to the server (e.g. --http).

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

Subcommands (telegram <subcommand>):

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

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

# Remove local credentials and revoke the session
telegram logout

The auth command, its deprecated login alias, and logout are single-user and local-machine only -- they writethe on-disk Telethon session and the encrypted single-user config, so run them on themachine that hosts the stdio server. For remote / multi-user HTTP deployments,credentials are entered through the browser relay form instead (see theremote 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 telegram following the steps athttps://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Tools

MCP Resources

Comparison

How telegram 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/telegram.git
cd telegram
uv sync
uv run telegram

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 thesame username always lands you in the same per-sub bucket, so your session staysreachable across a re-authorization and across devices, instead of being tied tothe one-off subject minted for each /authorize round-trip. Leaving it blankkeeps the previous per-authorize behaviour.

Trust boundary: when the form is gated by a shared MCP_RELAY_PASSWORD, theusername is a partition key, not a secret -- anyone who knows that password cantype any username and reach that bucket. That is fine for a trusted group; anuntrusted multi-tenant deployment needs a per-user secret or delegated OAuthinstead.

One-time migration: existing users must re-authenticate once after thischange. Nothing is deleted; sessions stored under the old random subject aresimply no longer addressed.

License

Apache-2.0 -- See LICENSE.