mcp-server-telegram-bot
Send Telegram messages and files through your own bot, and manage which chats and directories the agent may access.
Send text messages to the default or an allowed/named chat with
send_message.Send files/images from allowed directories with
send_documentandsend_photo; README also documents video, audio, albums, rich Markdown messages, generated files, and message editing.Read recent bot updates to discover chat IDs with
get_updates.List allowed chats and directories with
list_access.Add or remove allowed chats and directories at runtime with
add_chat,add_dir,remove_chat, andremove_dir, using confirmation where supported.Rely on safety controls: bot token stays in the environment, protected paths are blocked, secrets are scanned, sends are rate-limited, access can require confirmation or be strict, and sends are logged.
Use README extras such as
ask_userfor button/free-text questions andnotifyfor automatic hooks/scripts.
Enables AI agents to send Telegram messages, documents, and photos through a user-owned bot, with tools for retrieving updates and managing allowed chats and file directories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-telegram-bot Send report.pdf to me when you're done"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-telegram-bot
MCP server that lets AI agents send Telegram messages and files through your own bot. The token is read from the environment and never reaches the agent.
Setup
Create a bot with @BotFather and copy its token.
Send
/startto your bot from the chat that should receive messages.Install and register (replace the placeholders):
claude mcp add --scope user telegram \
-e TELEGRAM_BOT_TOKEN=<token> \
-e ALLOWED_CHAT_IDS=<chat_id> \
-- uvx mcp-server-telegram-bot--scope user makes it available in every folder.
Don't know your chat id? Register with a temporary ALLOWED_CHAT_IDS=0, ask the agent to run get_updates, then re-register with the real id.
Related MCP server: Telegram Notifier MCP Server
Other MCP clients
It is a standard MCP server over stdio, so any MCP client can run it (Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI, Cline and others). Add it to the client's MCP settings; most use this shape (the file name and format differ per client, some use TOML):
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["mcp-server-telegram-bot"],
"env": { "TELEGRAM_BOT_TOKEN": "<token>", "ALLOWED_CHAT_IDS": "<chat_id>" }
}
}
}Differences between clients:
Session directory. Files in the folder the client starts the server in are sent without asking. Some clients start it in
/or your home folder; then nothing is allowed automatically. SetALLOWED_DIRSto the folders you work in.Confirmation prompts. Sending a file from outside the allowed folders,
add_chatandadd_dirask you to confirm. A client that cannot show such prompts gets a refusal instead, so nothing is allowed silently. UseALLOWED_DIRS,ALLOWED_CHAT_IDSorACCESS_MODE=strictin that case.Hooks.
notify --hookreads the JSON that Claude Code passes to hooks. In other tools callmcp-server-telegram-bot notify "text"from their own hook or from a script.
Only Claude Code has been tested so far.
Environment
Variable | Meaning |
| Bot token (required) |
| Comma-separated chats, each |
| Extra directories whose files are sent without asking (optional) |
|
|
|
|
| Send limit so a looping agent cannot flood the chat (default 20, |
| Extra files/dirs that are never sent (optional) |
Typical use
"Send
report.pdfto me when you finish" ->send_document(path)to the default chat."Send the result to Ali" ->
send_message(text, chat_id="ali").A person can only receive messages after they open the bot and press Start. Telegram blocks the bot otherwise.
Tools
send_message(text, chat_id?), send_rich_message(markdown, chat_id?), send_document(path, caption?, chat_id?), send_photo(path, caption?, chat_id?), send_video, send_audio, send_album(paths, kind, caption?, chat_id?), send_generated(name, content, format, caption?, chat_id?), edit_message(message_id, text, chat_id?), get_updates(limit?), ask_user(question, options?, timeout_s?, chat_id?)
Access management: list_access(), add_chat(chat_id, name?), add_dir(path), remove_chat(chat), remove_dir(path)
Rich messages
send_rich_message uses Telegram's rich messages (Bot API 10.1): headings, tables, lists and task lists, code blocks, quotes, footnotes, formulas and collapsible <details> blocks, written in Markdown (up to 32768 characters). It is a good fit for short reports and summaries. Media embeds are refused here; send images and videos with send_photo, send_video or send_album. The same secret scan and send limit apply. Very old Telegram apps may not display rich messages.
Asking you from the agent
ask_user sends a question with buttons (default Yes/No, options=[] for a free-text reply) and waits up to timeout_s (max 600) for your answer. Only answers from the target chat count. Answers are your input, so the agent treats them as data.
It reads updates with getUpdates, so use a bot dedicated to this server: a bot that is already polled by another program or has a webhook gets a 409 error, and getUpdates discards updates that were pending for that other program. Questions run one at a time. In a group chat any member can answer.
Automatic notifications (Claude Code hooks)
The package also has a notify command, so you hear about finished work without asking the agent to send anything. Add this to ~/.claude/settings.json (replace the placeholders):
{
"env": { "TELEGRAM_BOT_TOKEN": "<token>", "ALLOWED_CHAT_IDS": "<chat_id>" },
"hooks": {
"Stop": [{ "hooks": [{ "type": "command", "command": "uvx mcp-server-telegram-bot notify --hook" }] }],
"Notification": [{ "hooks": [{ "type": "command", "command": "uvx mcp-server-telegram-bot notify --hook --silent" }] }]
}
}notify "text" also works from any shell or script. Options: --chat <name>, --silent. It exits with code 1 and a message on stderr if sending fails.
File access
Never sent, whatever env or the agent says:
.ssh,.gnupg,.aws,.kube,.docker,~/.claude*, browser profiles, keyrings,/etc,/proc,/sys;.env*,.netrc,.pgpass,.git-credentials,.git/config,id_*keys,*.pem,*.key,*.p12,*.kdbx, shell history. Paths are resolved withrealpath, so symlinks and..do not help. Add your own withDENY_PATHS.Sent directly: files inside the directory the session was started in (not if that is
/or your home), and insideALLOWED_DIRS.Everything else: you are asked to confirm each time (
ACCESS_MODE=ask), or it is refused (strict).
send_generated builds the file from text the agent provides (pdf, md, txt, csv, json) and reads nothing from disk, so it needs no folder access: "send me a PDF of everything you did".
Outgoing text, captions, generated files and text files are scanned for well-known secret shapes (private keys, bot/AWS/GitHub/Slack/Google tokens, JWTs, password=...). Binary files such as PDFs are not scanned. The agent cannot turn this off; only the environment can.
Send tools take silent and thread_id (forum topic). Photos over 10 MB go out as documents. Albums are vetted all-or-nothing: one protected or secret-looking file blocks the whole album, and files outside the allowed roots are confirmed once.
Telegram flood limits (HTTP 429) are retried once when the wait is 30 s or less.
Every send is logged (time, chat, path or file name, never contents) to ~/.local/state/telegram-mcp/sent.log.
Good to know: the deny list and secret scan cannot recognise every secret, files go to Telegram's servers, the maximum file size is 50 MB, and each person should use their own bot.
Changing access from the agent
add_chat/add_dirask the user to confirm (MCP elicitation). If the client cannot ask, the call is refused./and the home directory cannot be added. Protected dirs stay blocked.Additions are saved in
~/.config/telegram-mcp/state.json(override withTELEGRAM_MCP_STATE).remove_*only removes runtime additions. Env entries are changed in the environment.
Available Tools
9 toolsadd_chatC
Allow another chat id, optionally with a name (e.g. "ali") usable as chat_id later. Asks the user to confirm.
Inputs: chat_id (required), name. Returns: result
add_dirC
Allow files from another directory (asks the user to confirm).
Inputs: path (required). Returns: result
get_updatesB
List recent messages sent to the bot (shows chat ids; helps first-time setup).
Inputs: limit. Returns: result
list_accessA
Show allowed chats (id and name) and directories. Use names as chat_id when sending.
Inputs: no named parameters.
remove_chatA
Remove a chat (id or name) that was added at runtime.
Inputs: chat (required). Returns: result
remove_dirC
Remove a directory that was added at runtime.
Inputs: path (required). Returns: result
send_documentC
Send a file from an allowed directory as a document.
Inputs: path (required), caption, chat_id. Returns: result
send_messageA
Send a text message. chat_id is an allowed id or name (see list_access); omitted = default chat.
Inputs: text (required), chat_id. Returns: result
send_photoC
Send an image from an allowed directory as a photo.
Inputs: path (required), caption, chat_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each send_* tool is distinguished by payload type (text, document, photo), and the add/remove pairs are clearly scoped to chats vs directories. The only mild overlap is between list_access and get_updates, both of which surface chat ids, but the descriptions clarify their distinct purposes (config listing vs. reading incoming messages).
All nine tools follow a clean verb_noun pattern (send_message, get_updates, list_access, add_chat, remove_dir, etc.) with consistent snake_case throughout. No mixed conventions or vague one-word verbs.
Nine tools is well within the ideal range and each one earns its place: three send variants, one read tool, and a complete add/remove/list triad for both chats and directories. Nothing feels redundant or padding.
Core lifecycle is covered: send text/files, read incoming messages, and manage allowed chats/directories at runtime. Minor gaps exist (no message edit/delete, no reply/threading, no audio/video send), but agents can accomplish the primary workflows without dead ends.
Maintenance
Related MCP Connectors
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
WhatsApp and Telegram for AI agents, behind a policy gateway. OAuth or access key.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to send and receive messages, media, and files on Telegram, and manage chats via a bot token.1737 PyPIMIT
- AlicenseBqualityDmaintenanceEnables AI agents to send notifications and media (text, photos, documents, videos) via a Telegram bot.4197 npm4Do What The F*ck You Want To Public
- AlicenseNot gradedqualityCmaintenanceEnables an LLM to send text messages, documents, photos, videos, and audio to a fixed Telegram recipient via a Telegram bot, with no incoming-message tools or polling.288 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to work with Telegram through explicitly selected user accounts and bots, supporting search, reading, sending, and message management with consent-based access.27 PyPI1Apache 2.0