Skip to main content
telegram-channels-mcp: Claude reads, searches and analyzes your Telegram channels

Install  |  Tools  |  Safety  |  По-русски

CI Python 3.10+ MCP server MIT


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

Claude asks for channel stats and the best post, then drafts a post and shows a preview before sending

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)

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 login

Login 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-mcp

Check 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
list_chats Your channels, groups and chats. admin_only leaves only the ones you run
read_messages Latest posts or messages of any channel or chat, with views, reactions, comment count and links
search_messages Telegram's own full-text search inside one channel or chat
channel_stats Subscribers, average and median views, reach %, reactions, posts per day, best post
top_posts Best posts for the last N days by views, reactions, forwards or comments
get_comments Comments under a channel post
publish_post Post text or text with an image to your channel. Preview first, sends only with the confirm token
reply_comment 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 restarts
  • Both 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 channel
  • Claude 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=1 removes the write tools. TELEGRAM_WRITE_ALLOWLIST=mychannel limits writing to the channels you list
  • There 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
TELEGRAM_API_ID, TELEGRAM_API_HASH Your app keys from my.telegram.org
TELEGRAM_SESSION_PATH Session file location, default ~/.telegram-channels-mcp/session
TELEGRAM_SESSION_STRING Session as a string (login --string), handy for servers and containers
TELEGRAM_READ_ONLY 1 hides publish_post and reply_comment
TELEGRAM_WRITE_ALLOWLIST Comma-separated usernames or ids where writing is allowed
TELEGRAM_MCP_HOME Config folder, default ~/.telegram-channels-mcp

Check the session any time:

uvx telegram-channels-mcp whoami

Troubleshooting

  • 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: run login with another TELEGRAM_SESSION_PATH and put that path into its env
  • Telegram session is not authorized: run login again. The session also ends if you terminate it in Telegram → Settings → Devices
  • Long 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

MIT License

Metadata

Release files for telegram-channels-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for telegram-channels-mcp 0.1.0
File Size Uploaded Provenance Actions
telegram_channels_mcp-0.1.0.tar.gz 779.8 kB With provenance Details for telegram_channels_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for telegram-channels-mcp 0.1.0
File Interpreter ABI Platform Actions
telegram_channels_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for telegram_channels_mcp-0.1.0-py3-none-any.whl

Total release size: 797.5 kB

Release files / telegram_channels_mcp-0.1.0.tar.gz

Download URL telegram_channels_mcp-0.1.0.tar.gz
Size 779.8 kB
Tags Source
SHA-256 checksum
How to use checksums
53f55f0c0256e69e239c309c16a9b0062219f908e8403412c9e4d3c7a24c6529
BLAKE2b-256 checksum
How to use checksums
3ebe077c45f8850cfd17cddc2d4ad39fe368d4601a739ce2a83e9aa6c10ebd25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / telegram_channels_mcp-0.1.0-py3-none-any.whl

Download URL telegram_channels_mcp-0.1.0-py3-none-any.whl
Size 17.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1598a1df63ea20f6a9158757a6eaec07660ed477fa7e2a2ff33e7413573e42cc
BLAKE2b-256 checksum
How to use checksums
b680a1f4c30312567e9988b1064dcc81614cab2336891c1773bd924d5348aa34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for telegram-channels-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for telegram_channels_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page