telegram-mcp-kit
Allows interaction with the Telegram Bot API, enabling sending messages, editing/deleting messages, managing chats (ban, unban, pin), sending photos and documents, and retrieving bot info.
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-kit send a message saying 'Hello everyone'"
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.
🚀 telegram-mcp-kit
MCP server that exposes the Telegram Bot API as tools for Claude Code (or any MCP client).
Table of Contents
Related MCP server: Telegram MCP Server
🚀 Quick Start
Get your bot token from @BotFather on Telegram. Once the server is configured, you can run /mcp inside Claude Code to verify it is connected.
🛠️ Installation
Get your bot token from @BotFather on Telegram first.
Option 1: From PyPI (recommended)
claude mcp add telegram-mcp-kit \
-e TELEGRAM_BOT_TOKEN=your-bot-token-here \
-e TELEGRAM_CHAT_ID=your-chat-id \
-- uvx telegram-mcp-kit{
"mcpServers": {
"telegram-mcp-kit": {
"command": "uvx",
"args": ["telegram-mcp-kit"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here",
"TELEGRAM_CHAT_ID": "your-chat-id"
}
}
}
}Option 2: From GitHub
claude mcp add telegram-mcp-kit \
-e TELEGRAM_BOT_TOKEN=your-bot-token-here \
-e TELEGRAM_CHAT_ID=your-chat-id \
-- uvx --from "git+https://github.com/QuocTang/telegram-mcp-kit.git" telegram-mcp-kit{
"mcpServers": {
"telegram-mcp-kit": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/QuocTang/telegram-mcp-kit.git",
"telegram-mcp-kit"
],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here",
"TELEGRAM_CHAT_ID": "your-chat-id"
}
}
}
}Option 3: From source
git clone https://github.com/QuocTang/telegram-mcp-kit.git
cd telegram-mcp-kit
cp .env.example .env # add your TELEGRAM_BOT_TOKEN
uv syncclaude mcp add telegram-mcp-kit \
-- uv run --directory /absolute/path/to/telegram-mcp-kit telegram-mcp-kit{
"mcpServers": {
"telegram-mcp-kit": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/telegram-mcp-kit",
"telegram-mcp-kit"
]
}
}
}With this option,
TELEGRAM_BOT_TOKENis read from the.envfile inside the project directory.
Environment variables
Variable | Required | Description |
| Yes | Token from BotFather |
| No | Default chat ID (if set, |
| No |
|
| No | Bind host (default |
| No | Bind port (default |
| No | Telegram API timeout in seconds (default |
📦 Features
🚀 Feature | 📝 Description |
🛠️ 20+ Tools | Comprehensive coverage for messages, chat management, files/photos, and bot info. |
🔍 Auto-discovery | Simply add a Python file to the |
📡 Flexible Transport | Works seamlessly over stdio (for local clients) or SSE (remote/Docker). |
Tools List
Messages
Tool | Description |
| Send a text message (Markdown/HTML) |
| Edit an existing message |
| Delete a message |
| Forward a message between chats |
Updates
Tool | Description |
| Fetch recent messages/updates the bot received |
Chat management
Tool | Description |
| Get chat metadata (name, type, description) |
| Count members |
| List administrators |
| Ban a user |
| Unban a user |
| Change group/channel title |
| Change group/channel description |
| Pin a message |
| Unpin a message |
Files & photos
Tool | Description |
| Send a photo by URL or file_id |
| Send a local photo file |
| Send a document by URL or file_id |
| Send a local file as document |
| Get file metadata + download link |
Bot
Tool | Description |
| Get bot name, username, etc. |
🤝 How to Contribute
We welcome contributions! Please follow these steps:
Fork the repository.
Create a new branch for your feature.
Submit a Pull Request.
See CONTRIBUTING.md for how to add new tools.
Development
uv sync # install all deps (including dev)
uv run pytest -v # run tests
uv run ruff check src/ tests/ # lint💬 Community & Support
If this repository saves you time, please star the repository!
👥 Repo Contributors
Made with contrib.rocks.
⚖️ License
MIT License. See LICENSE for details.
🌟 Star History
Available Tools
20 toolsban_memberA
Ban a user from a chat.
Args: user_id: User ID to ban chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: user_id (required), chat_id. Returns: result
delete_messageB
Delete a message from a chat.
Args: message_id: ID of the message to delete chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: message_id (required), chat_id. Returns: result
edit_messageA
Edit an existing message.
Args: message_id: ID of the message to edit text: New text for the message chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) parse_mode: "Markdown", "MarkdownV2", or "HTML" (optional)
Inputs: message_id (required), text (required), chat_id, parse_mode. Returns: result
forward_messageB
Forward a message from one chat to another.
Args: from_chat_id: Source chat ID message_id: ID of the message to forward chat_id: Target chat ID (uses TELEGRAM_CHAT_ID if omitted)
Inputs: from_chat_id (required), message_id (required), chat_id. Returns: result
get_bot_infoA
Get information about the bot (name, username, etc.).
Inputs: no named parameters. Returns: result
get_chat_adminsB
Get list of administrators in a chat.
Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: chat_id. Returns: result
get_chat_infoA
Get information about a chat (group, channel, or private chat).
Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: chat_id. Returns: result
get_chat_member_countA
Get the number of members in a chat.
Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: chat_id. Returns: result
get_file_infoA
Get file info and download link from Telegram.
Args: file_id: Telegram file ID (from received messages)
Inputs: file_id (required). Returns: result
get_updatesA
Get recent messages/updates received by the bot.
Args: offset: Update ID offset (to get updates after a specific ID) limit: Maximum number of updates to return (1-100, default 100)
Inputs: offset, limit. Returns: result
pin_messageA
Pin a message in a chat.
Args: message_id: ID of the message to pin chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) silent: Pin without notification (default False)
Inputs: message_id (required), chat_id, silent. Returns: result
send_documentA
Send a document/file to a chat.
Args: document: Document URL or file_id chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Document caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)
Inputs: document (required), chat_id, caption, parse_mode. Returns: result
send_document_fileA
Send a local file as a document to a chat.
Args: file_path: Absolute path to the file on disk chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Document caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)
Inputs: file_path (required), chat_id, caption, parse_mode. Returns: result
send_messageA
Send a text message to a Telegram chat.
Args: text: Message text (supports Markdown/HTML based on parse_mode) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) parse_mode: "Markdown", "MarkdownV2", or "HTML" (optional) reply_to_message_id: ID of message to reply to (optional)
Inputs: text (required), chat_id, parse_mode, reply_to_message_id. Returns: result
send_photoA
Send a photo to a chat.
Args: photo: Photo URL or file_id chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Photo caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)
Inputs: photo (required), chat_id, caption, parse_mode. Returns: result
send_photo_fileA
Send a local photo file to a chat.
Args: file_path: Absolute path to the photo file on disk chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Photo caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)
Inputs: file_path (required), chat_id, caption, parse_mode. Returns: result
set_chat_descriptionA
Change the description of a chat (group/channel).
Args: description: New description (0-255 characters) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: description (required), chat_id. Returns: result
set_chat_titleA
Change the title of a chat (group/channel).
Args: title: New chat title (1-128 characters) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: title (required), chat_id. Returns: result
unban_memberA
Unban a user from a chat.
Args: user_id: User ID to unban chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)
Inputs: user_id (required), chat_id. Returns: result
unpin_messageB
Unpin a message in a chat.
Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) message_id: ID of message to unpin (optional, unpins most recent if not specified)
Inputs: chat_id, message_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 20 tools
All tools have distinct purposes with clear separation; similar pairs like send_document/send_document_file and send_photo/send_photo_file are differentiated by source type (URL/file_id vs local path).
All tool names follow a consistent verb_noun snake_case pattern (e.g., ban_member, get_chat_info, send_photo_file).
20 tools is on the higher end but covers core Telegram bot functionalities without being excessive. Each tool is justified.
Covers common messaging, moderation, and info retrieval but lacks support for sending stickers, audio, video, location, polls, and other media types, which are notable gaps for a full-featured Telegram toolset.
Maintenance
Related MCP Connectors
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with the Telegram Bot API via the Model Context Protocol to send, edit, and delete messages, photos, and videos. It allows Claude to manage Telegram communications and fetch bot updates through natural language commands.58 npm-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with the Telegram Bot API, allowing them to send messages, forward messages, get bot information, and receive updates.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send messages, media, and manage Telegram chat messages through a Telegram bot, including sending photos, documents, and editing or deleting messages.MIT
- FlicenseNot gradedqualityAmaintenanceExposes Telegram Bot API operations as MCP tools, enabling managing messages, chats, and forum topics via a FastMCP server.-