Telegram MCP

telegram

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
• Install
• Setup
• Smithery
• Configuration
• HTTP mode
• CLI
• Tools
• Comparison
• Security
• Build from Source
• Trust Model
• License

Features

• Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
• 6 tools with action dispatch: message, chat, media, contact, config, help
• Auto-detect mode -- Set a bot token for bot mode, or a phone number for user mode
• Local CLI auth -- telegram auth handles the bot token, or phone + OTP + 2FA, on the machine that runs the server
• Stdio or HTTP -- stdio by default; HTTP with no-auth (loopback only), a single bearer token, or per-user tokens
• 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, prompt-injection boundary tags on Telegram content

Install

# Claude Code plugin (stdio, bot mode)

/plugin marketplace add n24q02m/claude-plugins /plugin install better-telegram-mcp@n24q02m-plugins

Direct uvx invocation (stdio, bot mode)

claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx n24q02m-telegram

Docker stdio

docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

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

Install matrix

Install with AI agent -- paste this to your AI coding agent:

Install MCP server telegram following the steps at

https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Setup

Credentials are configured on the machine that runs the server.

Bot mode: set TELEGRAM_BOT_TOKEN in the client config, or save it once:

telegram auth --bot-token 123456:ABC-DEF

User mode: sign in interactively with your phone number. Telegram sends an OTP; a 2FA password is prompted if the account has one. The Telethon session is stored on disk.

telegram auth --phone +15551234567

Check the result with telegram status. The server reads saved credentials at startup, so restart it after telegram auth. Without any credentials the stdio server prints these instructions to stderr and exits with status 1.

Smithery

Also listed on Smithery. Per smithery.yaml, Smithery starts the server over stdio with uvx --python 3.13 n24q02m-telegram and takes no install-time configuration (empty configSchema). Credentials come from the TELEGRAM_BOT_TOKEN env var or a prior telegram auth (see Setup).

Configuration

Settings load from TELEGRAM_-prefixed environment variables (Pydantic Settings). Env vars take precedence over credentials saved by telegram auth.

There is no TELEGRAM_PASSWORD env var: telegram auth prompts for the 2FA password and never stores it in the environment.

HTTP mode

telegram --http serves MCP at /mcp and an unauthenticated GET /health. Settings live in ~/.telegram/config.toml:

[server]

host = "127.0.0.1" # default; --host overrides port = 8000 # default; --port overrides auth = "token" # "no-auth" | "token" | "multi" token_hash = "scrypt$..."

Create a token hash with telegram token hash (it reads the token from stdin or a prompt, never from the command line). In multi mode, add users by editing users.toml and restarting the server:

[users.alice]

token_hash = "scrypt$..." enabled = true namespace = "alice"

Then authorize Telegram for that user on the server machine:

telegram auth --phone +15551234567 --user alice

To reach a server on another machine, put it behind a TLS-terminating reverse proxy or a private network and use token or multi auth.

CLI

The telegram console script (installed by uvx / pip; better-telegram-mcp is a legacy alias) starts the MCP server when run without a subcommand. Flags that are not a subcommand are passed through to the server (for example --http, --host, --port).

telegram            # start the MCP server (stdio)

telegram --http # start in HTTP mode telegram --version # print the version

| config | config status, `config delete --ye