Telegram Mcp

Name: Telegram Mcp
Author: chigwell

communication MCP Server

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

bychigwell

Install Ready

communicationcommunication

9 views1,667 stars431 forksApache-2.0

View on GitHub

Why This Matters

Discovered via unknown and last synced 1w ago.

Install Ready

Source: unknown
Stars: 1,667
Last synced: 1w ago
Install: Instructions detected

Install

1. Install the package

uvx telegram-mcp

2. Add to claude_desktop_config.json

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uvx",
      "args": [
        "telegram-mcp"
      ]
    }
  }
}

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)

124

Tools

Resources

Prompts

Standard I/O

Transport

Available Tools (124)

Tool

Purpose

telegram_peers

List other shims connected to this daemon.

TELEGRAM_BG_MAX_PARALLEL

`3`

TELEGRAM_SPAWN_RATE_PER_HOUR

`5`

reply

Send text/files to a chat. Auto-chunks at 4096 chars.

TELEGRAM_STATE_DIR

`~/.claude/channels/telegram`

TELEGRAM_DAEMON_IDLE_EXIT

`604800` (7 days)

react

Set/clear emoji reaction on a message.

TELEGRAM_BOT_TOKEN

—

File

Purpose

TELEGRAM_BG_DEFAULT_WORKDIR

`$HOME`

TELEGRAM_SPAWN_CLAUDE_ARGS

auto (see below)

Command

Effect

TELEGRAM_BG_TIMEOUT

`30m`

TELEGRAM_PREFIX_ALIAS

`1`

TELEGRAM_SPAWN_DEFAULT_WORKDIR

`$HOME`

TELEGRAM_BG_RATE_PER_HOUR

`10`

TELEGRAM_ACCESS_MODE

`dynamic`

TELEGRAM_SPAWN_IDLE_TIMEOUT

`4h`

send_photo

发送图片

pin_message

置顶消息

send_contact

发送联系人

get_contacts

获取联系人列表

get_members

获取群组成员

join_channel

加入公开频道

unpin_message

取消置顶

send_location

发送位置

search_contacts

搜索联系人

get_admins

获取管理员列表

get_dialogs

获取对话列表

search_messages

搜索消息

send_reaction

发送表情反应

delete_contact

删除联系人

kick_from_chat

踢出群组

create_schedule

创建定时任务

get_chats

获取聊天列表（分页支持）

delete_messages

删除消息

send_voice

发送语音

get_user_info

获取用户详情

create_supergroup

创建超级群组

unban_user

解除封禁

get_pending_ai_tasks

获取待 AI 润色任务

search_chat

搜索公开群组/频道

forward_messages

转发消息

send_audio

发送音频

get_user_status

获取用户在线状态

create_channel

创建频道

set_group_photo

设置群头像

execute_ai_task

执行润色后发送

leave_chat

离开聊天

reply_message

回复消息

mark_read

标记已读

send_poll

创建投票

add_contact

添加联系人

invite_to_chat

邀请进群

send_video

发送视频

send_file

发送文件

get_me

获取我的信息

create_group

创建群组

ban_user

封禁用户

toggle_schedule

启用/禁用任务

get_messages

获取消息

block_user

拉黑用户

promote_admin

提升管理员

list_schedules

查看所有任务

unblock_user

解除拉黑

demote_admin

降级管理员

delete_schedule

删除任务

edit_group_title

编辑群名称

schedule_message

定时发送消息

set_group_permissions

设置群权限

get_invite_link

获取邀请链接

download_media

下载媒体

get_file_info

获取文件信息

get_bot_info

Return metadata about the configured bot

send_message

Send a message to the configured Telegram chat

Version

URL

get_chat_info

获取聊天详情

get_updates

Fetch recent pending messages received by the bot

medium

high

TELEGRAM_FORUM_CHAT_ID

—

TELEGRAM_SPAWN_MAX_PARALLEL

`3`

TELEGRAM_SPAWN_CLAUDE_BIN

auto (see below)

TELEGRAM_TOPIC_HEADER_REFRESH

`5s`

TELEGRAM_TYPING_REFRESH

`1` (on)

TELEGRAM_TYPING_DONE_EMOJI

`👌`

TELEGRAM_SHIM_LOG_DISABLE

`0` (sink on)

TELEGRAM_SHIM_LOG_TTL

`168h` (7d)

TELEGRAM_ADMIN_DENY_TOOLS

— (none)

TELEGRAM_ADMIN_ERRBURST_WINDOW

`1m`

DM

Render every known topic + lock state (DM-only, allowlisted).

TELEGRAM_BG_CLAUDE_BIN

auto (see below)

TELEGRAM_FORUM_AUTOSPAWN_DISABLE

`0` (enabled)

TELEGRAM_TOPIC_HEADER

`1` (on)

TELEGRAM_CORRUPT_TTL

`168h` (7d)

TELEGRAM_LOG_MAX_BYTES

`10485760` (10 MiB)

TELEGRAM_ADMIN_PENDING_TTL

`5m`

TELEGRAM_ADMIN_ERRBURST_THRESHOLD

`20`

edit_message

Edit a previously-sent message in place.

Variable

Default

TELEGRAM_TOPIC_ORPHAN_AFTER

`12h`

TELEGRAM_SPAWN_HARD_TIMEOUT

`24h`

TELEGRAM_TOPIC_HEADER_TICK

`60s`

TELEGRAM_TYPING_TTL

`60`

TELEGRAM_INBOX_TTL

`168h` (7d)

TELEGRAM_SHIM_LOG_MAX_BYTES

`2097152` (2 MiB)

TELEGRAM_ADMIN_ENABLE

`0` (off)

TELEGRAM_ADMIN_MUTATE_RATE_PER_HOUR

`60`

TELEGRAM_ADMIN_ERRBURST_COOLDOWN

`5m`

TELEGRAM_TOPIC_PURGE_AFTER

`12h`

TELEGRAM_TYPING_ROTATION_EMOJIS

`👀,🤔,✍`

TELEGRAM_ADMIN_MODEL

claude default

TELEGRAM_FORUM_AUTOSPAWN_COOLDOWN

`90s`

TELEGRAM_SESSIONS_TTL

`1h`

TELEGRAM_ADMIN_SITREP_INTERVAL

`24h`

Value

Transport

stdio

stdio (default)

http

streamable HTTP

sse

SSE (legacy HTTP)

Where

Effect

TELEGRAM_ASK_TIMEOUT

`110`

max

ultra` sets the model and thinking-token budget used by future `/spawn` and `/bg` runs from that chat (`ultra` = Claude Fable 5). Persisted across daemon restarts. - **Live status feedback** — while the agent works the daemon keeps a "typing…" bubble alive and rotates a reaction emoji on your message; in forum mode each topic carries a pinned header showing the owning session's state (🟢 idle · 🟡 busy · 🔵 awaiting permission · ⚪ disconnected), workdir, label, and uptime. - **MarkdownV2 output** — opt-in formatted replies, bold/italic/code/spoiler. - **Local-only, single-user** — no webhook, no public ingress, no DB. Long polling behind any NAT. --- ## How it works ``` Claude Code session ─┐ ┌─ Telegram Bot API │ │ (stdio MCP) │ │ (HTTPS long-poll) ▼ │ ┌──────────────┐ IPC (unix sock) ┌─────────┴──────────┐ │ shim │ ◄──────────────► │ daemon │ │ (per CC pid)│ │ (one per host) │ └──────────────┘ │ - bot token │ │ - access gate │ │ - shim router │ └────────────────────┘ ``` - **Shim** — stdio MCP plugin Claude Code launches. Holds no token. Speaks IPC to the daemon. Tied to its parent CC process by `PR_SET_PDEATHSIG`. - **Daemon** — one per host. Owns the bot token, runs the long-poller, holds the allowlist gate, routes inbound messages to the right shim. Auto-spawned by the first shim that needs it, or run permanently under systemd. A single Telegram message can be routed by: 1. **Forum topic** — when forum mode is on, a message inside a topic owned by a shim routes to that shim exclusively (mentions/reply-to inside the topic are ignored — the topic *is* the address). 2. **Reply-to** — Telegram's reply UI threads the message to whichever shim sent the original. 3. **Mention** — `@s2`, `@all`, or `@<label>` if the shim was labeled. 4. **Chat affinity** — last shim that talked in the chat wins (with TTL). 5. **LRU fallback** — most-recently-connected shim. --- ## Quick start ### 1. Build ```bash git clone https://github.com/yashok111/telegram-mcp.git cd telegram-mcp make build # → bin/telegram-mcp ``` Requires **Linux** and **Go 1.26**. macOS/Windows are not supported — the daemon/shim lifecycle depends on `PR_SET_PDEATHSIG` and `/proc/<pid>/comm`. Optional: `make lint` needs `golangci-lint` v2 built with Go 1.26 — `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`. ### 2. Create a bot Talk to [@BotFather](https://t.me/BotFather) on Telegram, run `/newbot`, collect the token. ```bash mkdir -p ~/.claude/channels/telegram echo 'TELEGRAM_BOT_TOKEN=123456:AA...' > ~/.claude/channels/telegram/.env chmod 600 ~/.claude/channels/telegram/.env ``` ### 3. Register with Claude Code ```bash claude mcp add telegram -s user -- $(pwd)/bin/telegram-mcp ``` If the marketplace bun plugin is enabled, disable it first to avoid 409s fighting over the same token: ```bash claude plugin disable telegram ``` Restart the Claude Code session. ### 4. Launch Claude Code with dev channels enabled Telegram inbound is delivered as `notifications/claude/channel/*` — an experimental MCP capability that Claude Code only honors when launched with `--dangerously-load-development-channels`. Without the flag the daemon and shim both log successful delivery, but the LLM never sees the message. Add a shell alias and use it whenever you want a Telegram-aware session: ```bash # ~/.zshrc or ~/.bashrc alias claude-tg='claude --dangerously-load-development-channels plugin:telegram@local-yakov' ``` Then launch with `claude-tg` instead of `claude`. The `plugin:telegram@local-yakov` arg is harmless for the MCP-server install path (it loads nothing extra) and is required for `/spawn`-launched sessions where the bot forks a fresh CC that needs the plugin name to match. ### 5. Pair your account On first run the daemon prints a pairing code. DM the bot from your real Telegram account with that code; the daemon adds you to the allowlist in `access.json`. Run `/telegram:access` (skill bundled in the project) for the managed pairing flow. --- ## Forum-topic mode (optional) Instead of every Claude Code session sharing the bot's single DM, point the bot at a **supergroup with topics enabled** and get one topic per session — one tab per project, persistent across `/exit`/restart. ### Setup 1. In Telegram: **New Group** → add the bot → group settings → enable **Topics**. 2. Add the bot as **Administrator** with **Manage Topics** permission. 3. Get the chat id (any inbound from the group is logged in `daemon.log` as `chat_id=-100…`). 4. Add the chat id to `~/.claude/channels/telegram/.env`: ```bash echo 'TELEGRAM_FORUM_CHAT_ID=-1002…' >> ~/.claude/channels/telegram/.env ``` 5. Restart the daemon. Every new `claude-tg` session triggers `createForumTopic` on hello, names it `@s<N> — <workdir-basename>`, and binds the shim. ### Behavior - **Outbound** — every `reply` / `react` / `edit_message` from a bound shim auto-fills `message_thread_id`. Replies land in the shim's topic. - **Inbound inside a topic** — routed to that topic's owning shim exclusively. `@all`, mentions, and reply-to are ignored — the topic itself is the address. - **Inbound in General** (`thread_id=0`) — routed by mention / reply / LRU exactly as before. `@all` still broadcasts. - **Permission prompts** — for shims with a topic, the prompt card lands in the topic next to the tool output that triggered it (not in DM). - **Pinned header** — each topic gets a pinned status message the daemon maintains in place: owning alias, state icon (🟢 idle · 🟡 busy · 🔵 awaiting permission · ⚪ disconnected · 🔴 closed), workdir, label, last activity, and uptime. Toggle with `TELEGRAM_TOPIC_HEADER=0`. ### Persistence and reuse Topics are **kept** when you `/exit`. The shim's lock drops; the topic mapping in `access.json` stays. Next CC session in the same workdir (or with the same `--label`) re-attaches to the existing topic, history intact. Reuse key priority: 1. `label:<L>` if `/label` was set on the shim. 2. `workdir:<path>` when workdir ≠ `$HOME` (random shell sessions from `$HOME` get fresh topics, not a shared bucket). 3. Otherwise a fresh topic. Dead topics are reaped automatically. A topic whose owner disconnected is closed after `TELEGRAM_TOPIC_ORPHAN_AFTER` (default 12h) of idleness; a duplicate topic (a second concurrent session in the same workdir) is closed within the hour once its session leaves; `/topic close` does it on demand. Closed topics are then deleted by a background sweep after `TELEGRAM_TOPIC_PURGE_AFTER` (default 12h) — so a dead topic fully disappears within ~24h. Raise either env var to keep topics around longer (reattaching to a still-open topic preserves its history). ### `/topic` commands

download_attachment

Fetch a `file_id` into `~/.claude/channels/telegram/inbox/`.

ask

Ask a multiple-choice question (2–10 inline buttons) and **block** until the operator taps one; returns the chosen option. Times out after `TELEGRAM_ASK_TIMEOUT`.

Works Well With - Skills

c-telegram

Bidirectional Telegram bridge — talk to Claude from your phone. Built into OpenPaw.

4 starsHas guide

c-slack

Send messages and upload files to Slack channels using the `slack` CLI. Supports direct messages, channel posts, file uploads, and thread replies.

4 starsHas guide

mesh-awareness

Discover agents across local node and mesh peers at runtime — their roles, handles, and how to communicate with or delegate to them.

3 starsHas guide

storytelling-with-data

Apply data visualization and storytelling principles from Storytelling with Data by Cole Nussbaumer Knaflic. Covers choosing effective visuals (line, bar, table, scatterplot), eliminating clutter (Gestalt principles, data-ink ratio), focusing attention (preattentive attributes, strategic color), thinking like a designer (affordances, alignment, white space), and narrative structure (three-act story, horizontal/vertical logic, Big Idea). Trigger on "data visualization", "chart design", "dashboard design", "data storytelling", "presentation chart", "declutter chart", "bar chart", "line chart", "data narrative", "slide deck data", "chart review", "viz critique", "storytelling with data".

2 stars

Works Well With - Agents

Auto Empirical Research Skills

🔬 A curated collection of 23,000+ agent skills for empirical research across 8 social science disciplines. | 精选 23,000+ AI Agent 技能库，覆盖8大社会科学学科的实证研究。CoPaper.AI 20分钟完成一篇可复现的规范实证论文，并支持用户上传 Skills。-- Maintained by CoPaper.AI from Stanford REAP.

4108 starslangchain

Awesome Agent Skills For Empirical Research

3716 starslangchain

AgentNetworkProtocol

AgentNetworkProtocol(ANP) is an open source protocol for agent communication. Our vision is to define how agents connect with each other, building an open, secure, and efficient collaboration network for billions of intelligent agents.

1426 stars