Better Telegram MCP
Provides comprehensive access to Telegram via both the Bot API and MTProto (user accounts). Enables managing messages, chats, media, and contacts, including capabilities like searching message history, managing group memberships, and interacting with the Telegram network as either a bot or a full user account.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
telegram
mcp-name: io.github.n24q02m/telegram
Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.
Project | Tagline | Tag |
Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling | |
Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace | |
Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP | |
IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP | |
Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and ... | Tooling | |
hull is the shared monorepo core for the wet, crg and mnemo self-hosted stack | MCP | |
Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling | |
Persistent AI memory with hybrid search. Open, free, unlimited. | MCP | |
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP | |
Secrets without the server. | CLI | |
A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling | |
Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP | |
Docs portal for the n24q02m open-source tool stack (skret, MCP plugins, hull,... | Tooling | |
Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP | |
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,helpAuto-detect mode -- Set a bot token for bot mode, or a phone number for user mode
Local CLI auth --
telegram authhandles the bot token, or phone + OTP + 2FA, on the machine that runs the serverStdio 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,openWorldHintMCP Resources -- Documentation available as
telegram://docs/*resourcesSecurity 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/telegramThe 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 |
|
Cursor / Windsurf / Gemini CLI / any MCP client |
|
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
telegramfollowing 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-DEFUser 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 +15551234567Check 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 |
| Bot mode | Bot token from @BotFather (format |
| User mode | Phone number in |
| No | Override the bundled public API pair |
| No | Set to |
| No | Telethon session file name (default |
| No | Session directory (default |
| No | Set to |
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$..."
| Who can connect | Credentials used |
| Anyone who can reach the port; loopback binds only (a non-loopback host is refused) | The default credentials |
| Clients sending | The default credentials |
| Users listed in | 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 aliceTo 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 versionSubcommand | Usage | Description |
|
| Authorize this machine. Bot mode validates the token; phone mode runs the interactive OTP/2FA flow and stores the Telethon session on disk |
| Same arguments as | Deprecated alias of |
|
| Revoke the Telegram session, delete the session file and the saved credentials |
|
| Show or delete the saved credential config |
|
| Show whether credentials are configured |
|
| Print environment diagnostics |
|
| Hash a bearer token for |
--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 mediaThe 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 |
|
| Send, edit, delete, forward messages. Pin, react, search, browse history |
|
| List and manage chats, groups, channels. Members, admin, forum topics |
|
| Send photos, files, voice notes, videos. Download media from messages |
|
| List, search, add contacts. Block/unblock users (user mode only) |
|
| Server status, runtime settings ( |
| -- | Full documentation for any topic |
MCP Resources
URI | Content |
| Message operations reference |
| Chat management reference |
| Media send/download reference |
| Contact management reference |
| 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 telegramTrust 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) |
| AES-256-GCM with the machine key |
Telethon sessions |
| File permission 0600 |
HTTP bearer tokens |
| 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Unified messaging MCP server: WhatsApp, Instagram, Telegram, SMS, Messenger & email support inbox
Related MCP Servers
- AlicenseBqualityDmaintenanceFull-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.1007MIT
- AlicenseAqualityDmaintenanceA 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.35Apache 2.0
- AlicenseNot gradedqualityBmaintenanceTelegram MTProto-based MCP server with 19 tools for reading, searching, sending, forwarding, and summarizing messages3MIT
- AlicenseNot gradedqualityBmaintenanceDual-plane Telegram MCP server providing read-only analytics and guarded write actions with built-in rate limiting, anti-spam protection, and session management.10MIT