telegram-channels-mcp
Provides a comprehensive interface to manage and analyze private and public Telegram channels and groups, allowing AI agents to read posts, search for content, gather detailed channel statistics (subscribers, views, reach), read comments, draft replies, and publish new content after user confirmation.
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-channels-mcp give me stats for my channel: subscribers, average views, best post this week"
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 server that connects Claude to your own Telegram account. Ask Claude to read a channel, find an old post, compare this week's reach with last week's, draft a post and publish it after you say yes
It works through the Telegram user API (Telethon), so it sees what you see in your app: public channels, your private channels and groups, comments under posts. The session file stays on your computer
What you can ask
"What did @durov post this month? Summarize in 5 bullets"
"Search my channel for posts about pricing and give me the links"
"Stats for my channel: subscribers, average views, best post of the week"
"Which of my last 30 posts got the most reactions, and what do they have in common?"
"Read the comments under my latest post and draft replies to the questions"
"Write a post about the update with this image and publish it to my channel" (Claude shows a preview first)
Related MCP server: telegram-mcp-server
Install
You need uv and your own api_id / api_hash from my.telegram.org/apps
1. Log in once (asks for api_id, api_hash, phone, code and 2FA password right in your terminal):
uvx telegram-channels-mcp loginLogin code doesn't arrive? Run uvx telegram-channels-mcp login --qr and scan the QR code in Telegram → Settings → Devices → Link Desktop Device
Latest code from GitHub instead of PyPI: replace uvx telegram-channels-mcp with uvx --from git+https://github.com/Kochurin/telegram-channels-mcp telegram-channels-mcp
Keys go to ~/.telegram-channels-mcp/.env, the session to ~/.telegram-channels-mcp/session.session. Nothing is sent anywhere except Telegram
2. Connect to Claude Code:
claude mcp add telegram -- uvx telegram-channels-mcpCheck with /mcp inside Claude Code
Or connect to Claude Desktop. Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["telegram-channels-mcp"]
}
}
}Restart Claude Desktop. If it can't find uvx, put the full path, for example C:\Users\you\.local\bin\uvx.exe (write it with double backslashes inside JSON) or /Users/you/.local/bin/uvx
Want a read-only setup? Add "env": {"TELEGRAM_READ_ONLY": "1"} and the write tools disappear
Tools
Tool | What it does |
| Your channels, groups and chats. |
| Latest posts or messages of any channel or chat, with views, reactions, comment count and links |
| Telegram's own full-text search inside one channel or chat |
| Subscribers, average and median views, reach %, reactions, posts per day, best post |
| Best posts for the last N days by views, reactions, forwards or comments |
| Comments under a channel post |
| Post text or text with an image to your channel. Preview first, sends only with the confirm token |
| Comment under your post or reply to a specific comment. Preview first, sends only with the confirm token |
Chats can be passed as @username, a t.me link, a t.me/c/... link or a numeric id from list_chats
Safety
Write tools never send on the first call. They return a preview and a one-time
confirm_token, Claude shows the preview to you, and only after your yes repeats the call with the token. The token is tied to the exact text, channel and image, so the post can't change between your yes and the send. It dies when the server restartsBoth write tools carry the destructive hint, so Claude Code and Claude Desktop ask your permission before each call unless you allowed it for good
Only pictures (
.jpg,.png,.webp,.gif) can be attached. A prompt injection in someone's post can't make Claude upload a private file to your channelClaude is told that text from Telegram is data, not instructions
Posting and replying work only in channels where you are the owner or an admin with posting rights
TELEGRAM_READ_ONLY=1removes the write tools.TELEGRAM_WRITE_ALLOWLIST=mychannellimits writing to the channels you listThere is no tool for private messages, deleting or editing. Claude can read your chats but can't write to people
The session file is a full key to your account. Don't commit it, don't share it, and if it leaks, end that session in Telegram → Settings → Devices
Settings
All optional except the API keys. Put them in ~/.telegram-channels-mcp/.env or into env of the MCP config. See .env.example
Variable | Meaning |
| Your app keys from my.telegram.org |
| Session file location, default |
| Session as a string ( |
|
|
| Comma-separated usernames or ids where writing is allowed |
| Config folder, default |
Check the session any time:
uvx telegram-channels-mcp whoamiTroubleshooting
database is locked: two copies of the server use one session file, for example Claude Code and Claude Desktop at the same time. Give the second one its own session: runloginwith anotherTELEGRAM_SESSION_PATHand put that path into itsenvTelegram session is not authorized: runloginagain. The session also ends if you terminate it in Telegram → Settings → DevicesLong pauses: Telegram limits request rates (FloodWait). Telethon waits out short limits by itself. If it happens often, ask for fewer posts at once
Run from source
git clone https://github.com/Kochurin/telegram-channels-mcp
cd telegram-channels-mcp
uv run telegram-channels-mcp login
npx @modelcontextprotocol/inspector uv run telegram-channels-mcp
uv run pytestПо-русски
MCP-сервер, через который Claude работает с вашим Telegram: читает каналы и чаты, ищет по каналу, считает статистику ваших каналов (подписчики, просмотры, охват, лучший пост за неделю), публикует пост с картинкой и отвечает в комментариях
Работает через ваш аккаунт, сессия хранится только у вас на компьютере. Публикация и ответы сначала показывают превью и уходят только после вашего «да». Писать в личку, удалять и редактировать сервер не умеет
Установка: получите api_id и api_hash на my.telegram.org/apps, выполните команду login из раздела Install и введите номер и код в своём терминале. Потом одна команда claude mcp add для Claude Code или блок JSON для Claude Desktop
Если Telegram в России тормозит или не грузит медиа, помогут бесплатные MTProto-прокси. Для остального интернета, в том числе на мобильном с белыми списками, есть @SkyrimVPN_bot, первые 3 дня бесплатно · сайт
Other projects
telegram-mtproto-proxy: free MTProto proxies for Telegram, updated every hour
blockcheck: check in your browser which services are blocked for you
awesome-obhod-blokirovok: tools for getting around internet blocks, in Russian
SkyrimVPN: VPN that works on mobile internet with whitelists, Telegram bot
MIT License
Available Tools
8 toolschannel_statsARead-only
Channel statistics: subscribers, views and reactions of the last N posts, average and median views, engagement rate and posting frequency. Works for any public channel, best for the user's own ones
Inputs: channel (required), posts. Returns: object
get_commentsBRead-only
Read comments under a channel post. Comment ids from here are used as comment_id in reply_comment
Inputs: channel (required), post_id (required), limit, max_chars. Returns: object
list_chatsBRead-only
List the user's Telegram dialogs: channels, groups and private chats, most recent first. Use admin_only=true to get only channels and groups the user owns or administers
Inputs: kind, limit, admin_only. Returns: result
publish_postADestructive
Publish a post to the user's own channel, optionally with one image.
DANGEROUS: the post becomes visible to all subscribers.
Without confirm_token nothing is sent: you get a preview and a confirm_token. Show the preview
to the user and repeat the call with the same arguments and confirm_token ONLY after the user
explicitly approves this exact text and channel.
image: local .jpg/.jpeg/.png/.webp/.gif file or https URL. With an image the caption limit is 1024 characters.
markdown: bold, italic, code, text
Inputs: text (required), channel (required), image, silent, +2 more. Returns: object
read_messagesARead-only
Read the latest messages or posts of a channel, group or private chat, newest first. chat: @username, t.me link or numeric id from list_chats. For older messages pass offset_id = the smallest id you already got. Text longer than max_chars is cut, use 0 for full text
Inputs: chat (required), limit, max_chars, offset_id. Returns: object
reply_commentADestructive
Write a comment under a post of the user's own channel, or reply to a specific comment there (comment_id from get_comments). The reply is sent from the user's account. DANGEROUS: it is public. Without confirm_token nothing is sent: you get a preview and a confirm_token. Show the preview to the user and repeat the call with the same arguments and confirm_token ONLY after the user explicitly approves this exact text
Inputs: text (required), channel (required), post_id (required), comment_id, +1 more. Returns: object
search_messagesARead-only
Full-text search inside one channel or chat using Telegram's own search, newest matches first
Inputs: chat (required), query (required), limit, max_chars. Returns: object
top_postsBRead-only
Best posts of a channel for the last N days, ranked by views, reactions, forwards or comments
Inputs: channel (required), days, limit, sort_by. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: listing chats, reading messages, searching, aggregate stats, ranked top posts, reading comments, publishing posts, and replying to comments. The only mild overlap is channel_stats versus top_posts, but one is aggregate analytics and the other is post ranking, so the descriptions make the boundary clear.
Most names follow a predictable verb_noun snake_case pattern: list_chats, read_messages, search_messages, get_comments, publish_post, reply_comment. The two exceptions are channel_stats and top_posts, which are noun-focused rather than verb_noun, but they remain readable and consistent in style.
Eight tools is well-scoped for a Telegram channels server, covering discovery, reading, analytics, comments, and publishing without obvious redundancy. Each tool earns its place in the workflow.
The surface covers the core lifecycle: list chats, read/search messages, inspect stats and top posts, read comments, publish, and reply. Minor gaps remain around editing or deleting published posts and retrieving detailed chat/channel metadata, but agents can still handle the main channel workflows.
Related MCP Connectors
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceEnables Claude to interact with your Telegram account, including reading messages, searching conversations, and sending messages.-
- FlicenseNot gradedqualityDmaintenanceEnables Claude to interact with Telegram, including listing chats, reading messages, sending messages, searching, and managing contacts.1-
- AlicenseNot gradedqualityDmaintenanceConnect Claude to your personal Telegram account via MTProto to read messages, search chats, send replies, forward files, and more using your real account.3MIT
- AlicenseBqualityCmaintenanceEnables Claude Code to control your own Telegram account via the MTProto API, including reading chats, sending and editing messages, posting to channels, managing groups, sending files, pressing inline buttons, and creating bots through BotFather.231MIT