Allows sending messages and photos through a Telegram bot to specified chats, including text messages with plain or HTML formatting and photo uploads from local paths or URLs.
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 Send a message to chat 123456789 saying the build finished successfully."
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.
Lets Claude Code and Claude Desktop send messages and photos through your Telegram bot. It runs locally and only makes outgoing calls to Telegram: it doesn't receive messages, open ports or need hosting.
Tool | Inputs | Notes |
|
| Text over 4096 characters is sent as several messages |
|
|
|
chat_id is always required. There is no default, so include it in your prompts, including scheduled task prompts.
format is plain (the default) or html for Telegram's HTML formatting.
A person must have started your bot, or a group or channel must have added it, before the bot can message them.
Related MCP server: telegram-mcp-kit
You need Node.js 20 or later on each computer, or 22.19 or later if the computer runs antivirus or a proxy that scans HTTPS.
Open PowerShell in this folder and run:
powershell -ExecutionPolicy Bypass -File .\install.ps1Open config.env and set TELEGRAM_BOT_TOKEN to your token from @BotFather.
Check the token. This doesn't send a message:
node server.mjs --checkRestart Claude Desktop and any open Claude Code sessions.
Copy this whole folder. You can leave out node_modules, which is only needed for development.
Run install.ps1 on the new computer.
Restart Claude.
You can also clone this repository instead of copying the folder. config.env is deliberately not in the repository, so after cloning, run install.ps1 and add your token to config.env as in Setup. server.mjs is included, so no build is needed.
Scheduled tasks are stored on each computer, not in this folder, so recreate them on the new computer and turn them off on the old one to avoid duplicate messages.
Run install.ps1 again if you move the folder on the same computer, because Claude's config stores its exact location. To remove the server from a computer you're finished with, run uninstall.ps1 there before moving the folder, then delete config.env if the folder stays behind.
Anyone with config.env can send messages as your bot, so keep this folder out of shared or public locations. If the token leaks:
Send /revoke to @BotFather in Telegram.
Put the new token in config.env.
No restart is needed, because the token is read on each send.
The server doesn't restrict recipients. Any chat that has started your bot can be messaged, and anyone who finds the bot can start it.
Keep Claude's approval prompt on for these tools in interactive sessions. Scheduled tasks need sending pre-approved, so be careful with tasks that read untrusted content such as web pages or emails, which could try to trick Claude into sending data.
send_photo can send any supported image file that Claude can name, including screenshots.
Message | What to do |
| Set |
| The token is wrong or was revoked |
| Antivirus or a proxy is intercepting HTTPS. The server trusts the Windows certificate store on Node 22.19 or later, so update Node |
| Check the ID, and that the chat has started or added the bot |
| The person needs to unblock the bot |
| The HTML is invalid; escape |
Tools don't appear in Claude | Fully quit Claude, including from the system tray, because closing the window leaves it running. Then reopen it, and run |
install.ps1 saves the previous version of each Claude config file with a .bak extension.
npm install
npm run build
npm testSource is in src/. npm run build bundles it into server.mjs and regenerates THIRD_PARTY_LICENSES.txt, so rebuild before running the tests or copying the folder.
MIT. See LICENSE. server.mjs also includes third-party packages, which are listed with their licenses in THIRD_PARTY_LICENSES.txt.
Send a text message through the Telegram bot. Text over 4096 characters is split into several messages.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Message text | |
| format | No | 'plain' sends text as is. 'html' uses Telegram HTML (<b>, <i>, <u>, <s>, <code>, <pre>, <a href>, <blockquote>); escape <, > and & in text as < > &. | plain |
| chat_id | Yes | Destination chat: a numeric ID, or @channelname for a public channel. Never guess this; ask the user if it is unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly=false, openWorld=true, non-idempotent and non-destructive, so the safety profile is covered. The description adds genuine value beyond them by disclosing that text over 4096 characters is split into multiple messages - a side effect that explains why one call can produce several deliveries. It could go further on failure modes or rate limits.
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?
Two tight sentences with zero filler, and the core action is front-loaded before the character-splitting caveat. Nothing could be removed without losing information.
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 three-parameter send tool with a fully documented schema and no output schema, the description covers purpose and the main surprising behavior (message splitting). Only secondary details such as error conditions or rate limiting are absent, which is minor at this 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?
Schema description coverage is 100%, including a detailed format enum and a chat_id note warning against guessing destinations, so the schema carries the parameter burden. The description adds no parameter-level meaning beyond that; baseline 3 applies.
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 names a specific verb and resource ('Send a text message') and the transport ('through the Telegram bot'), which clearly separates it from the send_photo sibling. It stops short of explicitly contrasting with that sibling, but the text-vs-photo distinction is unambiguous.
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?
Usage is implied by 'send a text message' - the agent knows this is the tool for outbound text. There is no explicit when-to-use, when-not-to-use, or prerequisite guidance (e.g. bot must be a member of the chat), leaving the agent to infer conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a photo through the Telegram bot from an absolute local path (.jpg, .jpeg, .png, .webp, up to 10 MB) or an http(s) URL.
| Name | Required | Description | Default |
|---|---|---|---|
| photo | Yes | Absolute local file path or http(s) URL | |
| format | No | 'plain' sends text as is. 'html' uses Telegram HTML (<b>, <i>, <u>, <s>, <code>, <pre>, <a href>, <blockquote>); escape <, > and & in text as < > &. | plain |
| caption | No | Optional caption, up to 1024 characters | |
| chat_id | Yes | Destination chat: a numeric ID, or @channelname for a public channel. Never guess this; ask the user if it is unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and non-idempotence, so the safety profile is covered by structured data. The description adds genuine behavioral constraints beyond that: a 10 MB size ceiling and a whitelist of supported formats (.jpg, .jpeg, .png, .webp), which affects whether an agent should even attempt the call. It does not cover failure modes or re-send behavior, but the file constraints are substantive added 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?
A single sentence, front-loaded with the action and resource, then the input forms and limits. No filler, no repetition of the title, and every clause carries constraint information an agent needs before calling.
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?
With only four parameters, full schema coverage, and annotations covering the safety profile, the definition supplies what is needed to invoke the tool correctly, including input constraints. There is no output schema, so no return format is described either, leaving the agent unaware of what the call yields (e.g., a message identifier) or what an error looks like, which is a minor but real gap for a network-side-effect operation.
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 both required parameters and the optional caption/format fields are already documented in the schema, including the 'never guess chat_id' warning and the HTML escaping rules. The description adds the file-format and size constraints for photo, which the schema's 'absolute local file path or http(s) URL' line does not, but that is a single increment over an otherwise schema-driven baseline.
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 gives a specific verb and resource ('Send a photo through the Telegram bot') and immediately names the two accepted photo sources: an absolute local path or an http(s) URL. It is trivially distinguishable from the only sibling, send_message, since the resource type differs, though it never explicitly contrasts the two.
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?
Usage is implied by the resource: call this when the user wants an image delivered to a chat. There is no explicit when-not guidance (e.g., use send_message for text or files, albums not supported) and no mention of prerequisites such as the bot needing access to the destination chat.
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.
v1.0.0send_messagesend_photoScored across 2 tools
The two tools have clearly distinct purposes: one sends text, the other sends an image from a path or URL. There is no realistic chance of an agent selecting the wrong tool for a given request.
Both tools follow the same verb_noun snake_case convention (send_message, send_photo) and are intuitively named. No mixed conventions or vague verbs.
Two tools is very thin for a server billed as a general Telegram integration. It is not wrong for a minimal outbound bot, but it sits at the borderline of a usable surface.
Outbound text and photo sending are covered, but there is no way to read incoming messages, edit or delete sent messages, or send other media such as documents, audio, or video. These are notable gaps for a Telegram messaging server that agents may stumble on.
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.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.