Provides tools for sending and managing messages, photos, documents, and chat operations (like pinning, deleting) via a Telegram bot.
Click on "Install 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.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Target chat. Use a numeric chat ID (e.g. 123456789 for a user, -1001234567890 for a supergroup/channel) or a public channel username with a leading '@' (e.g. '@my_channel'). If unknown, call telegram_get_updates after the user messages the bot to discover it. | |
| message_id | Yes | ID of the message to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deletion is permanent and irreversible, aligns with destructiveHint annotation. Adds details on permissions, time limits (48h), and error responses, going beyond the annotation's binary flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Error Handling). Every sentence is informative; no fluff. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavioral aspects (permanence, permissions, errors). Minor gap: the return format is only 'Confirmation of deletion' without specifics, but given the tool's simplicity and lack of output schema, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds value with examples for chat_id (numeric vs. @username) and suggests how to discover the chat ID, which is helpful beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a message from a chat' with a specific verb (delete) and resource (message from a chat). It distinguishes from sibling tools like edit, pin, unpin, send messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use: bots can always delete their own messages, deleting others requires admin rights. Includes error handling for common failures. Does not explicitly contrast with alternatives, but the usage conditions are well explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | New text for the message | |
| chat_id | Yes | Target chat. Use a numeric chat ID (e.g. 123456789 for a user, -1001234567890 for a supergroup/channel) or a public channel username with a leading '@' (e.g. '@my_channel'). If unknown, call telegram_get_updates after the user messages the bot to discover it. | |
| message_id | Yes | ID of the message to edit (returned by telegram_send_message) | |
| parse_mode | No | Text formatting mode. 'HTML' supports <b>, <i>, <a href>, <code>, <pre>. 'MarkdownV2' requires escaping special characters (_*[]()~`>#+-=|{}.!) with a backslash. 'none' sends plain text. | none |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations by disclosing the 48-hour time constraint, the bot-ownership requirement, and error handling details. Annotations indicate idempotentHint=true but description explains the 'message is not modified' error, adding behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear overview, constraints, Args list, Returns, and Error Handling sections. Every sentence provides value, no fluff, and the most critical info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, description covers purpose, constraints, and error handling. Not specifying exact return fields is a minor gap, but 'Confirmation that the message was updated' is adequate given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description partly repeats schema but adds minor value, such as character limits for text and formatting explanations for parse_mode. No significant new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit the text of a previously sent bot message.' The verb 'edit' and resource 'text of a previously sent bot message' are specific. It distinguishes from siblings like telegram_send_message (send new) and telegram_delete_message (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description specifies that only messages sent by this bot and younger than 48 hours can be edited, providing clear context. Error handling gives situations when it won't work. However, it does not explicitly name alternative tools for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Numeric chat ID or '@channel_username' to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying return fields and error cases, enhancing transparency beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with clear sections (purpose, args, returns, error handling). Every sentence is informative and earns its place, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, strong annotations, and full schema coverage, the description is complete: it explains what is returned, how to supply input, and common errors. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the property description is already clear. The description's 'Args' section restates the parameter format, adding no new semantics. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to look up details about a chat, listing specific returned fields (title/name, type, description, invite link). This distinctively identifies the tool from its siblings (send, delete, pin, etc.) which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides error handling conditions ('chat not found' scenarios) that implicitly guide when the tool can be used: only for chats the bot has interacted with. It doesn't explicitly compare with alternatives, but the context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by specifying the return shape (JSON with id, username, first_name, is_bot). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus 'Args: none' and 'Returns:' line. Front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completes all needs: purpose, usage, return structure, and no parameters. Annotations cover behavioral traits. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Description adds 'Args: none' which is clear. Baseline 4 for zero-parameter case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns basic info about the bot itself (username, ID, display name). This distinguishes it from sibling tools that deal with messages, chats, or updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states two use cases: verifying TELEGRAM_BOT_TOKEN validity and retrieving the bot's @username to start a chat. Does not mention when not to use, but context with siblings provides implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of recent updates to return (1-100, default 20) | |
| offset | No | Only return updates with update_id greater than or equal to this value. Omit to get the most recent updates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: calling consumes updates (non-idempotent behavior and long-polling semantics). This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary and labeled Args/Returns sections. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and complete schema coverage, the description covers all necessary aspects: purpose, usage, behavioral traits, and return format. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters fully described (limit range and offset semantics). The description repeats this information and adds no new parameter-level details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches recent incoming updates and identifies it as the primary way to discover a chat_id. It distinguishes itself from sibling tools like telegram_send_message by emphasizing its role in obtaining updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: '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'. It also notes that calling consumes updates. However, it lacks explicit exclusions or alternatives for scenarios where updates are not needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Target chat. Use a numeric chat ID (e.g. 123456789 for a user, -1001234567890 for a supergroup/channel) or a public channel username with a leading '@' (e.g. '@my_channel'). If unknown, call telegram_get_updates after the user messages the bot to discover it. | |
| message_id | Yes | ID of the message to pin | |
| disable_notification | No | If true, pins silently without notifying chat members |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds context by confirming that pinning is a mutation that returns a confirmation, and includes error handling for permission issues. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. It is front-loaded with the purpose, followed by a structured Args section and error handling. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 3 parameters, no output schema, and comprehensive annotations, the description covers the essential behavioral aspects: permission preconditions, parameter defaults, and known error cases. It could mention return structure (e.g., 'returns a message object'), but the current level is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by including error handling context ('can_pin_messages' permission) and specifying the default for disable_notification. This goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Pin a message at the top of a chat.' It uses a specific verb ('Pin') and resource ('message at the top of a chat'), and distinguishes from sibling tools like telegram_unpin_chat_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when the tool can be used by specifying permission requirements: 'Requires the bot to have pin permissions in groups/channels (not required for private chats with the bot).' It also gives an error handling example that helps agents diagnose issues. However, it does not explicitly compare usage against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| caption | No | Optional caption shown below the media, up to 1024 characters | |
| chat_id | Yes | Target chat. Numeric chat ID (e.g. 123456789) or '@channel_username' for public channels. | |
| document | Yes | Publicly accessible HTTPS URL of the file to send (e.g. 'https://example.com/report.pdf') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only or destructive, and the description adds context: Telegram fetches the file server-side, returns a confirmation with message_id, and describes common errors. These details go beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with clear sections (main purpose, Args, Returns, Error Handling), and front-loaded with the most important information. Every sentence adds meaningful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately explains the return value (confirmation with message_id) and common errors. All parameters are documented, and the tool's behavior regarding file size and accessibility is covered. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions, so baseline is 3. The description adds value by listing parameters in a structured 'Args' block and clarifying that the document URL must be public HTTPS and that caption has a 1024-character limit, which slightly exceeds the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a file (PDF, CSV, ZIP, etc.) to a Telegram chat via URL with an optional caption. It provides a specific verb-resource pair ('send a file') and distinguishes from siblings like telegram_send_photo and telegram_send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (sending documents by URL) but does not explicitly exclude cases like sending local files or when to use alternatives. It includes helpful error handling guidance and a size limit, which aids in correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Message text to send, e.g. 'Deploy finished successfully ✅' | |
| chat_id | Yes | Target chat. Use a numeric chat ID (e.g. 123456789 for a user, -1001234567890 for a supergroup/channel) or a public channel username with a leading '@' (e.g. '@my_channel'). If unknown, call telegram_get_updates after the user messages the bot to discover it. | |
| parse_mode | No | Text formatting mode. 'HTML' supports <b>, <i>, <a href>, <code>, <pre>. 'MarkdownV2' requires escaping special characters (_*[]()~`>#+-=|{}.!) with a backslash. 'none' sends plain text. | none |
| reply_to_message_id | No | If set, sends this message as a reply to the given message_id in the same chat | |
| disable_notification | No | If true, sends the message silently (no notification sound for recipients) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing the return value (confirmation with message_id), error scenarios (chat not found, 403 Forbidden), prerequisites (user must start chat), and effects (message sent). This comprehensively discloses the behavioral traits of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, errors). It is concise, front-loaded with the purpose, and every sentence adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, 2 required, no output schema), the description covers usage, parameter details, return value, error handling, and prerequisites (user must start chat). It is fully adequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all 5 parameters. The description largely repeats this information without adding significant extra meaning beyond clarifying usage via examples (e.g., 'from a scheduled routine'). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a text message to a Telegram chat, group, channel, or user via the bot.' It uses a specific verb+resource and distinguishes from sibling tools like telegram_send_photo and telegram_send_document by focusing on text messages and positioning itself as the primary tool for notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context: 'primary tool for pushing notifications, alerts, or updates into Telegram — e.g. from a scheduled routine or automation.' It implicitly suggests when to use this tool but does not explicitly exclude alternatives or mention when to use siblings. Error handling offers guidance on recovery, strengthening usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| photo | Yes | Publicly accessible HTTPS URL of the image to send (e.g. 'https://example.com/chart.png') | |
| caption | No | Optional caption shown below the media, up to 1024 characters | |
| chat_id | Yes | Target chat. Numeric chat ID (e.g. 123456789) or '@channel_username' for public channels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details beyond annotations, including the server-side fetching of the URL, specific error messages (wrong file identifier, IMAGE_PROCESS_FAILED), file size limit (10 MB), and format hints. This adds significant context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Error Handling sections. It is concise (no unnecessary information) and front-loaded with the main purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema) and good annotations, the description covers the main use case, constraints, and error scenarios. It lacks explicit mention of what happens if chat_id is invalid, but the schema already covers parameter formats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds value by clarifying that the photo URL is fetched server-side and by specifying error handling for the photo parameter, which is not in the schema. The parameter descriptions in the docstring largely mirror the schema but with added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends an image to a Telegram chat by URL with an optional caption. It distinguishes from siblings like telegram_send_message (text) and telegram_send_document (file) by specifying 'send an image' and 'by URL'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for sending images from public HTTPS URLs, but does not explicitly contrast with alternatives like telegram_send_document for files. The purpose is clear, but no 'when not to use' or direct sibling comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Target chat. Use a numeric chat ID (e.g. 123456789 for a user, -1001234567890 for a supergroup/channel) or a public channel username with a leading '@' (e.g. '@my_channel'). If unknown, call telegram_get_updates after the user messages the bot to discover it. | |
| message_id | No | ID of the message to unpin. Omit to unpin the chat's most recent pinned message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive nature. The description adds behavior for omitting message_id and states the return value ('Confirmation of unpinning'). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single line plus an args section. All sentences are necessary and information-dense. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers the purpose, parameter behavior, and return value. It could mention error cases but is adequate given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description provides a concise summary but does not add significant new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Unpin a message') and the resource ('in a chat'). It distinguishes from siblings like 'telegram_pin_chat_message' and 'telegram_delete_message' by its specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the optional message_id and default behavior (unpins most recent if omitted). However, it does not explicitly state when not to use this tool or mention alternatives beyond the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0telegram_delete_messagetelegram_edit_message_texttelegram_get_chattelegram_get_metelegram_get_updatestelegram_pin_chat_messagetelegram_send_documenttelegram_send_messagetelegram_send_phototelegram_unpin_chat_messageEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Drive your real WhatsApp inbox from Claude — send, reply, label, assign, and triage via TimelinesAI.
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
Talk to Claude and get a live web app deployed to a real URL, with Postgres, storage and cron.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/germankingerman-byte/telegram-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
