Which integrations are available for this server?

Allows AI agents to seamlessly interact with Telegram using a Bot Token, enabling bidirectional communication: sending and receiving text messages, multimedia, documents, and managing chats.

How do I use agent-telegram-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-telegram-mcp Send a welcome message to the Telegram group" 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.

agent-telegram-mcp

by tharindumendis

Overview Schema Source Related Servers Discussions Admin

Python

Remote

agent-telegram-mcp

A robust Model Context Protocol (MCP) server that enables AI agents to seamlessly interact with Telegram using a standard Bot Token. It provides a comprehensive suite of tools for bidirectional communication, including sending and receiving text messages, multimedia, documents, and managing chats.

Installation

Install using pip or uv:

pip install agent-telegram-mcp

uv tool install agent-telegram-mcp

Related MCP server: Telegram Notifier MCP Server

Configuration

This MCP server requires a Telegram Bot Token. You can create a new bot and obtain your token by talking to the BotFather on Telegram.

To use this server with MCP-compatible clients (like Claude Desktop, Agent_head, etc.), add it to your server configuration and pass the token as an environment variable:

Example `mcp_config.json`

{
  "mcpServers": {
    "agent-telegram-mcp": {
      "command": "agent-telegram-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
      }
    }
  }
}

Available Tools

The server exposes the following tools to the LLM agent:

✉️ Messaging

telegram_send_message: Send text messages (supports Markdown, HTML, silent messages, and replies).
telegram_forward_message: Forward existing messages between chats.
telegram_delete_message: Delete a message from a chat (requires bot admin permissions).
telegram_pin_message: Pin a message in a group/channel.

🖼️ Media & Files

telegram_send_photo: Send images via a local file path, public HTTP URL, or Telegram file ID.
telegram_send_video: Send video files.
telegram_send_audio: Send audio tracks (renders as a Telegram music player).
telegram_send_voice: Send voice notes (.ogg files).
telegram_send_document: Send arbitrary files (PDFs, ZIPs, code snippets, etc.).
telegram_send_sticker: Send .webp stickers.
telegram_send_location: Send a geographic map pin via latitude and longitude.

📥 Retrieval & Info

telegram_get_updates: Retrieve recent messages, commands, and callback queries sent to the bot (supports pagination with offset and limit).
telegram_get_chat_info: Fetch detailed information about a user, group, or channel.
telegram_get_chat_member_count: Check how many users are in a chat.
telegram_get_file_info: Retrieve metadata and the download path for a file hosted on Telegram servers.
telegram_download_file: Download a file to a specific local path or return its contents as a Base64 string.
telegram_get_bot_info: Fetch the current bot's profile information to verify the token connection.

Development & Testing

You can run the server directly via standard I/O (stdio) transport:

export TELEGRAM_BOT_TOKEN="your-token"
# On Windows: set TELEGRAM_BOT_TOKEN=your-token

agent-telegram-mcp

Available Tools

17 tools

telegram_delete_messageA

Destructive

Delete a message from a chat (bot must have delete permission).

Args: params (DeleteMessageInput): chat_id and message_id to delete.

Returns: str: JSON {"deleted": true} on success or an error description.

Inputs: params (required). Returns: result

telegram_download_fileA

Read-onlyIdempotent

Download a file from Telegram using its file_id.

If save_path is provided, writes the file to disk and returns the path. Otherwise returns the file content as base64-encoded string.

Use telegram_get_file_info first if you only need the download URL.

Args: params (DownloadFileInput): file_id, optional save_path.

Returns: str: JSON with saved_path or base64 content + filename and size.

Inputs: params (required). Returns: result

telegram_forward_messageA

Forward a message from one chat to another.

Args: params (ForwardMessageInput): target chat_id, from_chat_id, message_id.

Returns: str: JSON with the forwarded Message object or an error description.

Inputs: params (required). Returns: result

telegram_get_bot_infoA

Read-onlyIdempotent

Get information about the configured bot (name, username, capabilities).

Useful to verify the bot token is valid and check bot identity.

Returns: str: JSON with User object representing the bot.

Inputs: no named parameters. Returns: result

telegram_get_chat_infoB

Read-onlyIdempotent

Get information about a chat (group, channel, or user).

Returns name, type, description, member count, and more.

Args: params (GetChatInput): chat_id or @username.

Returns: str: JSON with Chat object details.

Inputs: params (required). Returns: result

telegram_get_chat_member_countA

Read-onlyIdempotent

Get the total number of members in a chat/channel/group.

Args: params (GetChatMembersCountInput): chat_id or @username.

Returns: str: JSON with {"member_count": N}.

Inputs: params (required). Returns: result

telegram_get_file_infoA

Read-onlyIdempotent

Get metadata and download path for a file stored on Telegram servers.

Returns the file_path needed to construct the download URL: https://api.telegram.org/file/bot/<file_path>

Args: params (GetFileInput): file_id of the Telegram file.

Returns: str: JSON with File object including file_path, file_size, and download_url.

Inputs: params (required). Returns: result

telegram_get_updatesA

Read-onlyIdempotent

Retrieve recent updates (messages, callbacks, etc.) sent to the bot.

Use the 'offset' parameter to mark previous updates as read and paginate. Call with offset = (last_update_id + 1) to acknowledge processed messages.

Args: params (GetUpdatesInput): offset, limit, allowed_updates filter list.

Returns: str: JSON list of Update objects containing messages and metadata.

Inputs: params (required). Returns: result

telegram_pin_messageA

Idempotent

Pin a message in a chat (bot must be admin with pin_messages permission).

Args: params (PinMessageInput): chat_id, message_id, disable_notification flag.

Returns: str: JSON {"pinned": true} on success or an error description.

Inputs: params (required). Returns: result

telegram_send_audioA

Send an audio file to a Telegram chat (shown as music player).

Accepts a local file path, a public HTTP(S) URL, or a Telegram file_id.

Args: params (SendAudioInput): chat_id, audio source, optional caption/performer/title.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_documentA

Send any file (document) to a Telegram chat.

Use this for PDFs, ZIPs, code files, or any file type that doesn't fit photo/video/audio. Accepts a local path, URL, or Telegram file_id.

Args: params (SendDocumentInput): chat_id, document source, optional caption.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_locationB

Send a geographic location (map pin) to a Telegram chat.

Args: params (SendLocationInput): chat_id, latitude, longitude.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_messageA

Send a text message to a Telegram chat.

Supports plain text, Markdown, and HTML formatting. Can reply to an existing message using reply_to_message_id.

Args: params (SendMessageInput): Validated input with chat_id, text, parse_mode, reply_to_message_id, and disable_notification.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_photoA

Send a photo to a Telegram chat.

Accepts a local file path, a public HTTP(S) URL, or a Telegram file_id. Optionally include a caption (supports Markdown/HTML).

Args: params (SendPhotoInput): chat_id, photo source, optional caption/parse_mode.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_stickerA

Send a sticker to a Telegram chat using a file_id or .webp URL.

Args: params (SendStickerInput): chat_id and sticker file_id or URL.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_videoA

Send a video to a Telegram chat.

Accepts a local file path, a public HTTP(S) URL, or a Telegram file_id.

Args: params (SendVideoInput): chat_id, video source, optional caption, dimensions.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

telegram_send_voiceA

Send a voice message (.ogg/Opus) to a Telegram chat.

Accepts a local file path, a public HTTP(S) URL, or a Telegram file_id.

Args: params (SendVoiceInput): chat_id, voice file source, optional caption/duration.

Returns: str: JSON with the sent Message object or an error description.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-05-29 21:45 across 17 tools

Disambiguation5/5

Each tool targets a distinct operation: sending different media types, managing messages, retrieving info, etc. No two tools have overlapping purposes.

Naming Consistency5/5

All tools follow a consistent 'telegram_verb_noun' pattern (e.g., telegram_send_message, telegram_get_chat_info), making them predictable and easy to navigate.

Tool Count4/5

With 17 tools, the set is slightly large but still well-scoped for a Telegram bot covering messaging, media, and info retrieval. It covers the essentials without being excessive.

Completeness4/5

The tool set covers core Telegram bot operations (send, receive, manage messages, media, files). Minor gaps exist, such as no edit_message or webhook management, but it is functional for most use cases.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Agent Outbox for TelegramA
io.roxinbox
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Communication Social Media
31
https://outbox.roxinbox.io/mcp
AdminHub for Telegram
tools.adminhub
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Communication Social Media
1
https://mcp.adminhub.tools/mcp
telegram-mcp
io.github.Shreyas-Profile
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Communication App Automation
2
https://telegram.regiq.in/api/mcp
Felku Connect
br.com.felku.mcp
WhatsApp and Telegram for AI agents, behind a policy gateway. OAuth or access key.
Communication Security
1
https://mcp.felku.com.br/mcp

Related MCP Servers

Telegram MCP Server
Communication Workplace & Productivity
NexusX-MCP
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with the Telegram Bot API, allowing them to send messages, forward messages, get bot information, and receive updates.
Updated 2 years ago (2025-04-13 11:32 UTC)
14 npm
3
MIT
Telegram Notifier MCP Server
Communication App Automation
harnyk
A
license
B
quality
D
maintenance
Enables AI agents to send notifications and media (text, photos, documents, videos) via a Telegram bot.
Updated a year ago (2025-08-31 06:58 UTC)
4
567 npm
4
Do What The F*ck You Want To Public
tg-account-mcp
Communication App Automation
Mesteriis
A
license
Not graded
quality
B
maintenance
Enables AI agents to work with Telegram through explicitly selected user accounts and bots, supporting search, reading, sending, and message management with consent-based access.
Updated 11 days ago (2026-11-04 16:05 UTC)
40 PyPI
1
Apache 2.0
Telegram MCP Server
Communication App Automation
ivantelix
A
license
A
quality
C
maintenance
Enables AI assistants to interact with Telegram via the Bot API, including sending messages, media, polls, and managing chats and updates.
Updated 2 months ago (2026-09-25 23:32 UTC)
16
MIT

agent-telegram-mcp

Installation

Configuration

Example mcp_config.json

Available Tools

✉️ Messaging

🖼️ Media & Files

📥 Retrieval & Info

Development & Testing

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Telegram MCP Server

Telegram Notifier MCP Server

tg-account-mcp

Telegram MCP Server

Example `mcp_config.json`