Skip to main content
Glama
Better Telegram MCP

Better Telegram MCP

by n24q02m

telegram

mcp-name: io.github.n24q02m/telegram

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

Project

Tagline

Tag

better-semantic-release

Drop-in python-semantic-release fork with built-in release-safety guards (orp...

Tooling

claude-plugins

Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...

Marketplace

crg

Knowledge graph for token-efficient code reviews -- semantic search and call-...

MCP

email

IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...

MCP

fastretrieval

Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and ...

Tooling

hull

hull is the shared monorepo core for the wet, crg and mnemo self-hosted stack

MCP

jules-task-archiver

Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...

Tooling

mnemo

Persistent AI memory with hybrid search. Open, free, unlimited.

MCP

notion

Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...

MCP

skret

Secrets without the server.

CLI

tacet

A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl...

Tooling

telegram

Telegram for AI agents -- messages, chats, media, and contacts across both bo...

MCP

tools-docs

Docs portal for the n24q02m open-source tool stack (skret, MCP plugins, hull,...

Tooling

wet

Open-source MCP server for AI agents: web search, content extraction, and lib...

MCP

workspace

Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...

MCP

Table of contents

Related MCP server: Telegram MCP Server & Channel Monitor

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 telegram@n24q02m-plugins

# Direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx --python 3.13 n24q02m-telegram@latest

# Docker: the image runs the HTTP server and needs a config.toml with
# auth = "token" or "multi" (see HTTP mode)
docker run --rm -p 127.0.0.1:8080:8080 \
  -v "$PWD/config.toml:/home/appuser/.telegram/config.toml:ro" \
  -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 is io.github.n24q02m/telegram, the Docker image is n24q02m/telegram, and the legacy better-telegram-mcp command is kept as an alias of telegram. The pre-rename registry entry io.github.n24q02m/better-telegram-mcp stays frozen in the registry and is never republished. Local data moves once from ~/.better-telegram-mcp to ~/.telegram on first start.

Install matrix

Client

Install

Claude Code

/plugin marketplace add n24q02m/claude-plugins + /plugin install telegram@n24q02m-plugins (stdio bot mode), or claude mcp add as in the block above

Cursor / Windsurf / Gemini CLI / any MCP client

mcpServers JSON in the client's config: stdio command, or type: "http" + url pointing at a server you run (see HTTP mode)

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/telegram/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@latest 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.

Variable

Required

Description

TELEGRAM_BOT_TOKEN

Bot mode

Bot token from @BotFather (format 123456789:ABCdef...)

TELEGRAM_PHONE

User mode

Phone number in +<country><number> form

TELEGRAM_API_ID / TELEGRAM_API_HASH

No

Override the bundled public API pair

USE_BUNDLED_TELEGRAM_CLIENT

No

Set to false to require your own API pair

TELEGRAM_SESSION_NAME

No

Telethon session file name (default default)

TELEGRAM_DATA_DIR

No

Session directory (default ~/.telegram)

MCP_TRANSPORT

No

Set to http to start in HTTP mode (--http or TRANSPORT_MODE=http also work)

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$..."

auth

Who can connect

Credentials used

no-auth

Anyone who can reach the port; loopback binds only (a non-loopback host is refused)

The default credentials

token

Clients sending Authorization: Bearer <token> matching token_hash

The default credentials

multi

Users listed in users.toml (default ~/.telegram/users.toml), each with their own token

Each user's own namespace

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.

The Docker image (n24q02m/telegram, also ghcr.io/n24q02m/telegram) runs this HTTP server, not a stdio server: its entrypoint is python -m telegram --http --host 0.0.0.0 --port 8080, and MCP_TRANSPORT=stdio does not change that. Because it binds a non-loopback address, the default no-auth mode exits with status 2. Mount a config.toml with auth = "token" at /home/appuser/.telegram/config.toml (for "multi", also mount its users.toml). For stdio, use uvx or build the stdio stage of the Dockerfile (docker buildx build --target stdio).

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

Subcommand

Usage

Description

auth

auth --bot-token <token> or auth --phone <+number>, optional --user <ns>

Authorize this machine. Bot mode validates the token; phone mode runs the interactive OTP/2FA flow and stores the Telethon session on disk

login

Same arguments as auth

Deprecated alias of auth

logout

logout [--yes] [--user <ns>]

Revoke the Telegram session, delete the session file and the saved credentials

config

config status, config delete --yes

Show or delete the saved credential config

status

status

Show whether credentials are configured

doctor

doctor

Print environment diagnostics

token

token hash

Hash a bearer token for config.toml / users.toml

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

Tool commands

Every MCP tool is also a one-shot CLI command: <tool> <action> [flags] takes the tool's own arguments, calls the same handler the MCP server registers, and connects the backend for that single call -- no server process and no MCP client involved. --json prints the tool result as JSON; without it the result is key: value lines. A tool error goes to stderr and exits 1.

# message: send, edit, delete, forward, pin, react, search, history
telegram message send --chat-id @mychannel --text "deploy is green"
telegram message history --chat-id=-1001234567890 --limit 5 --json
telegram message search --query "invoice" --json

# chat: list, info, create, join, leave, members, admin, settings, topics
telegram chat list --json
telegram chat members --chat-id @mychannel --limit 100

# media: send_photo, send_file, send_voice, send_video, download
telegram media send_photo --chat-id @mychannel --file-path-or-url ./shot.png --caption "nightly"
telegram media download --chat-id 123456789 --message-id 42 --output-dir ./media

# contact: list, search, add, block (user mode only)
telegram contact search --query "An"
telegram contact block --user-id 123456789 --unblock

# settings: status, set, cache_clear -- the MCP tool named `config`
telegram settings status
telegram settings set --key message_limit --value 50

# help: full documentation, no credentials needed
telegram help media

The MCP tool config is telegram settings on the CLI, because config is hull's operator command for the saved credential blob. Negative chat ids must be attached with = (--chat-id=-1001234567890), otherwise argparse reads them as a flag. --user <ns> selects the namespace, as for the operator commands.

Tools

Each tool below is one MCP tool and one CLI group (telegram <tool> <action>, see Tool commands); both call the same handler.

Tool

Actions

Description

message

send, edit, delete, forward, pin, react, search, history

Send, edit, delete, forward messages. Pin, react, search, browse history

chat

list, info, create, join, leave, members, admin, settings, topics

List and manage chats, groups, channels. Members, admin, forum topics

media

send_photo, send_file, send_voice, send_video, download

Send photos, files, voice notes, videos. Download media from messages

contact

list, search, add, block

List, search, add contacts. Block/unblock users (user mode only)

config

status, set, cache_clear

Server status, runtime settings (message_limit, timeout), cache

help

--

Full documentation for any topic

MCP Resources

URI

Content

telegram://docs/messages

Message operations reference

telegram://docs/chats

Chat management reference

telegram://docs/media

Media send/download reference

telegram://docs/contacts

Contact management reference

telegram://stats

All documentation combined

Comparison

How telegram stacks up against direct competitors in each pillar:

Capability

telegram

chigwell/telegram-mcp

sparfenyuk/mcp-telegram

guangxiangdebizi/telegram-mcp

Bot API mode (bot token)

Yes (httpx)

No

No

Yes

MTProto user-account mode

Yes (Telethon)

Yes

Yes

No

Send / edit / delete messages

Yes

Yes

No (read-only, draft only)

Yes (send only)

Media download from messages

Yes

Yes

Yes

No (send only)

Contact management (add / block)

Yes (user mode)

Yes

Partial (list only)

No

Multi-user HTTP, per-user isolation

Yes (per-user tokens and namespaces)

No

No

No

SSRF protection

Yes (URL validation + DNS-rebinding)

?

?

No

Path-traversal prevention

Yes

Yes (real-path allowed-root)

?

No

Self-hostable

Yes

Yes

Yes

Yes

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

Data

Location

Protection

Saved credentials (bot token / phone)

~/.telegram/config.json; ~/.telegram/subs/<ns>/config.json in multi mode

AES-256-GCM with the machine key ~/.telegram/.secret

Telethon sessions

~/.telegram/<name>.session; ~/.telegram/subs/<ns>/ in multi mode

File permission 0600

HTTP bearer tokens

token_hash in config.toml / users.toml

Stored only as scrypt hashes

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

License

Apache-2.0 -- See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Full-featured Telegram Bot API server for MCP (Model Context Protocol). 174 tools covering the entire Bot API — messages, chats, stickers, payments, forums, stories, and more.
      100
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A comprehensive MCP server providing 35 tools for managing Telegram messages, media, and chat interactions via the Bot API. It also features a real-time monitoring system using the Telethon User API to log messages from specific channels.
      35
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Dual-plane Telegram MCP server providing read-only analytics and guarded write actions with built-in rate limiting, anti-spam protection, and session management.
      10
      MIT