Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.
The MCP server better-telegram-mcp provides “Telegram for AI agents,” focused on messages, chats, media, and contacts. It supports both bot and user-account modes, enabling an MCP client to access Telegram data and work with those entities in an agent workflow.
🛠️ Key Features
Messages
Chats
Media
Contacts
Bot and user-account modes
🚀 Use Cases
Building AI agents that read and process Telegram messages and chats
Handling media content associated with Telegram communications
Managing or syncing Telegram contacts for agent context
⚡ Developer Benefits
Aligns with Model Context Protocol (MCP) for tool-based integrations
Repository targets developer tooling and environments labeled with topics like python, mcp, docker, and telethon
⚠️ Limitations
The available source data does not specify authentication, rate limits, or supported Telegram API coverage beyond the listed capabilities.
# 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 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 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:
Credentials are configured on the machine that runs the server.
Bot mode: set TELEGRAM_BOT_TOKEN in the client config, or save it once:
bash
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.
bash
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.
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:
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:
Then authorize Telegram for that user on the server machine:
bash
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).
bash
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.
bash
# 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