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.

[Mode] [CI] [codecov] [PyPI] [Docker] [License: Apache-2.0]

[Python] [Telegram] [MCP] [semantic-release] [Renovate]

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 stdiodocker 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 overridesport = 8000          # default; --port overridesauth = "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 = truenamespace = "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 modetelegram --version  # print the version

--user selects the storage namespace (default default, used by stdio and the no-auth / token HTTP modes). Unknown subcommands exit with status 2.

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; the 2FA password is prompted, never stored in env vars
• Error Sanitization -- Credentials and bot tokens are never leaked in error messages or logs
• Prompt-injection boundaries -- Telegram content returned by tools is wrapped in untrusted-content tags

Build from Source

git clone https://github.com/n24q02m/telegram.gitcd telegramuv syncuv run telegram

Trust Model

The project does not operate a hosted Telegram endpoint. The server runs on infrastructure you control, and credentials never leave that machine.

Anyone with access to your OS user account can read these files.

License

Apache-2.0 -- See LICENSE.