Provides tools for sending and managing messages, photos, documents, and chat operations (like pinning, deleting) via a Telegram bot.
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., "@Telegram MCP Server send a reminder 'Meeting in 5 minutes' to chat 987654321"
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.
An MCP (Model Context Protocol) server that lets Claude send and manage messages in Telegram through a bot. Built for remote deployment (Streamable HTTP) so it keeps working even when your own computer is off — a requirement for using it inside Claude's scheduled routines/automations.
Tool | Purpose |
| Send a text message (the main tool for automations/alerts) |
| Edit a message the bot already sent |
| Delete a message |
| Pin/unpin a message |
| Send an image by URL with an optional caption |
| Send a file (PDF, CSV, etc.) by URL with an optional caption |
| Check the bot's identity / verify the token works |
| Look up info about a chat |
| Discover a chat's |
Related MCP server: mcp-telegram-claudecode
Open Telegram, search for @BotFather, and start a chat.
Send /newbot, give it a name and a username (must end in bot, e.g. my_claude_alerts_bot).
BotFather replies with a token that looks like 123456789:AAExampleTokenValueHere. Copy it —
this is your TELEGRAM_BOT_TOKEN. Keep it secret; anyone with it can control your bot.
Since the server needs to run even when your computer is off, deploy it to a free hosting platform. Render.com is the simplest option (no credit card needed for the free tier):
Push this folder to a new GitHub repository (create one at github.com if needed):
cd telegram-mcp-server
git init
git add .
git commit -m "Telegram MCP server"
git branch -M main
git remote add origin https://github.com/<your-username>/telegram-mcp-server.git
git push -u origin mainGo to render.com → sign up/log in → New + → Web Service.
Connect your GitHub account and select the telegram-mcp-server repo.
Configure it:
Build Command: npm install && npm run build
Start Command: npm start
Instance Type: Free
Under Environment Variables, add:
TELEGRAM_BOT_TOKEN = (the token from BotFather)
TRANSPORT = http
Click Create Web Service. After the first deploy finishes, Render gives you a URL like
https://telegram-mcp-server.onrender.com. Your MCP endpoint is that URL + /mcp, e.g.
https://telegram-mcp-server.onrender.com/mcp.
Note: on Render's free tier the service sleeps after 15 minutes of inactivity and takes ~30-60s to wake up on the next request. That's fine for occasional routine use; upgrade to a paid instance ($7/mo) if you need it always warm.
(Railway, Fly.io, or any other Node-friendly host work the same way — build command
npm install && npm run build, start command npm start, and the same two env vars.)
In claude.ai: Settings → Connectors → Add custom connector, paste your /mcp URL from Step 2,
and save. The tools listed above will then be available to Claude, including inside scheduled
routines/automations.
The bot can only message chats it already knows about:
To message yourself or a friend: that person must open a chat with the bot (search its
@username in Telegram) and send it any message, e.g. /start.
To message a group: add the bot to the group.
To message a channel: add the bot as an admin of the channel.
Then, in Claude, ask it to call telegram_get_updates — it will show the chat_id for every
chat/group/channel that has messaged the bot. Save that chat_id; you'll reuse it in your routine
(e.g. "send a Telegram message to chat_id 123456789 saying ...").
npm install
cp .env.example .env # fill in TELEGRAM_BOT_TOKEN
npm run build
# stdio mode (for Claude Desktop/Claude Code on your own machine)
npm start
# HTTP mode (matches what's deployed)
TRANSPORT=http PORT=3000 npm startTest with the MCP Inspector:
npx @modelcontextprotocol/inspectorNever commit .env or your bot token to git (.gitignore already excludes .env).
The bot token grants full control of the bot — treat it like a password.
This server only calls the official Telegram Bot API (api.telegram.org); it doesn't store any
message content itself.
Permanently delete a message from a chat. This cannot be undone.
Bots can always delete their own messages. Deleting other users' messages requires the bot to have admin/delete rights in a group or channel.
Args:
chat_id (string | number): Chat containing the message
message_id (number): ID of the message to delete
Returns: Confirmation of deletion.
Error Handling:
"message to delete not found" -> already deleted or too old (regular messages older than 48h generally can't be deleted by bots without admin rights).
"not enough rights" -> the bot needs admin permissions in this chat to delete others' messages.
Inputs: chat_id (required), message_id (required).
Edit the text of a previously sent bot message.
Only messages sent by this bot can be edited, and only if they were sent less than 48 hours ago.
Args:
chat_id (string | number): Chat containing the message
message_id (number): ID of the message to edit
text (string): Replacement text, 1-4096 characters
parse_mode ('Markdown' | 'MarkdownV2' | 'HTML' | 'none'): Text formatting (default: 'none')
Returns: Confirmation that the message was updated.
Error Handling:
"message to edit not found" -> wrong chat_id/message_id, or the message is older than 48 hours.
"message is not modified" -> the new text is identical to the current text.
Inputs: text (required), chat_id (required), message_id (required), parse_mode.
Look up details about a chat: title/name, type (private/group/supergroup/channel), description, and invite link if available.
Args:
chat_id (string | number): Numeric chat ID or '@channel_username'
Returns: JSON with id, type, title/name, description.
Error Handling:
"chat not found" -> the bot has never interacted with this chat. For private chats, the user must message the bot first; for groups/channels, the bot must be a member.
Inputs: chat_id (required).
Return basic info about the bot itself (username, ID, display name).
Useful to verify the configured TELEGRAM_BOT_TOKEN is valid and to get the bot's @username so a user can start a chat with it.
Args: none
Returns: JSON with id, username, first_name, is_bot.
Inputs: no named parameters.
Fetch recent incoming updates the bot has received (messages sent to it, chats it was added to, etc.). This is the primary way to discover a chat_id: ask the user to send any message to the bot (or add it to a group), then call this tool to read the resulting update and find the chat.id to use with telegram_send_message.
Note: calling this tool consumes the updates (Telegram's long-polling semantics), so previously fetched updates won't reappear on the next call once acknowledged.
Args:
limit (number): Max updates to return, 1-100 (default: 20)
offset (number, optional): Only return updates at/after this update_id
Returns: JSON list of updates with chat_id, chat type/title, sender, and message text for each.
Inputs: limit, offset.
Pin a message at the top of a chat. Requires the bot to have pin permissions in groups/channels (not required for private chats with the bot).
Args:
chat_id (string | number): Target chat
message_id (number): ID of the message to pin
disable_notification (boolean): Pin silently (default: false)
Returns: Confirmation of pinning.
Error Handling:
"not enough rights" -> the bot needs the 'can_pin_messages' admin permission in this chat.
Inputs: chat_id (required), message_id (required), disable_notification.
Send a file (PDF, CSV, ZIP, etc.) to a Telegram chat by URL, with an optional caption.
Args:
chat_id (string | number): Target chat
document (string): Public HTTPS URL of the file. Telegram fetches it server-side.
caption (string, optional): Caption text, up to 1024 characters
Returns: Confirmation with the new message_id.
Error Handling:
"wrong file identifier/HTTP URL specified" -> the URL is not publicly reachable.
Telegram limit for files sent by URL is 20 MB.
Inputs: chat_id (required), document (required), caption.
Send a text message to a Telegram chat, group, channel, or user via the bot.
This is the primary tool for pushing notifications, alerts, or updates into Telegram — e.g. from a scheduled routine or automation.
Args:
chat_id (string | number): Target chat ID or '@channel_username'
text (string): Message body, 1-4096 characters
parse_mode ('Markdown' | 'MarkdownV2' | 'HTML' | 'none'): Text formatting (default: 'none')
disable_notification (boolean): Send silently (default: false)
reply_to_message_id (number, optional): Reply to a specific earlier message
Returns: Confirmation text including the chat and the new message_id (needed later to edit/delete/pin it).
Error Handling:
"chat not found" -> the chat_id is wrong, or the user has never started a chat with the bot. Ask the user to send /start to the bot first, or use telegram_get_updates to find the right chat_id.
403 Forbidden -> the bot was blocked by the user or removed from the group/channel.
Inputs: text (required), chat_id (required), parse_mode, reply_to_message_id, +1 more.
Send an image to a Telegram chat by URL, with an optional caption.
Args:
chat_id (string | number): Target chat
photo (string): Public HTTPS URL of the image. Telegram fetches it server-side.
caption (string, optional): Caption text, up to 1024 characters
Returns: Confirmation with the new message_id.
Error Handling:
"wrong file identifier/HTTP URL specified" -> the URL is not publicly reachable or not a supported image format (jpg, png, gif, webp).
"IMAGE_PROCESS_FAILED" -> the file is too large (Telegram limit: 10 MB for photos sent by URL).
Inputs: photo (required), chat_id (required), caption.
Unpin a message (or the most recent pin) in a chat.
Args:
chat_id (string | number): Target chat
message_id (number, optional): Specific pinned message to unpin. If omitted, unpins the most recently pinned message.
Returns: Confirmation of unpinning.
Inputs: chat_id (required), message_id.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool targets a distinct action: getting bot info, sending messages, editing, deleting, pinning, unpinning, sending photos, sending documents, getting chat details, and fetching updates. No two tools have overlapping purposes.
All tools follow the pattern 'telegram_verb_noun' (e.g., telegram_send_message, telegram_get_chat). The naming is uniform and predictable, with clear verb-object relationships.
With 10 tools, the set is well-scoped for a Telegram bot server. It covers essential operations without being bloated or too sparse, fitting the typical use cases of message management and information retrieval.
The tool set covers core CRUD operations for messages (send, edit, delete, pin/unpin), media sending, and chat/update retrieval. Minor gaps exist (e.g., no forward_message, sticker, or inline query support), but the essential workflow is complete.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Post and schedule to X, LinkedIn, Bluesky, Mastodon and Telegram from an AI agent.