mcpField
T
telegram

telegram

github.com/skillhq生产力14477 次安装21 周前更新
代码仓库

关于 telegram

telegram 是用于操作 Telegram 对话和群组的命令行技能，支持搜索消息、管理聊天及导出历史记录，并提供适合终端查看或程序处理的输出格式。

主要功能

  1. 01读取并搜索聊天和消息
  2. 02发送消息与回复
  3. 03管理群组、成员和聊天文件夹
  4. 04静音或取消静音聊天
  5. 05同步并导出聊天历史
  6. 06支持人类可读、JSON 和 Markdown 输出

适用场景

  1. 01查找未读消息或搜索聊天
  2. 02发送私聊或群组消息
  3. 03查看成员并管理群组权限
  4. 04导出聊天记录或增量更新存档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/skillhq/telegram --skill telegram

安装后在 Claude Code 中输入/telegram确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

install.sh
CLAUDE.md
package.json
.gitignore
.clawdhubignore
README.md
package-lock.json
.github/workflows/
ci.yml
publish.yml
scripts/
publish-skill.sh
src/
auth.ts
client.ts
audit.ts
src/commands/
check.ts
chats.ts
folder-add.ts
auth.ts
contact.ts
folder-remove.ts
folder.ts
groups.ts
inbox.ts
folders.ts
logout.ts
index.ts
kick.ts
members.ts
mute.ts
promote.ts
read.ts

详细介绍

📬 Telegram CLI

用于读取、搜索和发送消息的快速 Telegram CLI。

🎯 适用场景

在用户遇到以下情况时使用此技能：

  • 要求查看 Telegram 消息或收件箱
  • 想要在 Telegram 中搜索某个主题／关键词
  • 想要发送 Telegram 消息或回复消息
  • 询问 Telegram 群组、联系人或聊天
  • 想要查看未读消息
  • 需要查找群组成员或管理员
  • 想要将嘈杂的聊天或群组静音／取消静音
  • 需要将用户踢出／移出群组
  • 想要将成员提升为管理员
  • 想要将群组／频道的所有权转让给其他人
  • 想要将聊天记录导出或同步到文件
  • 询问如何将聊天整理到文件夹中
  • 想要查看已登录的账号或会话状态

📦 安装

npm install -g @skillhq/telegram

🔐 身份验证

首次设置需要从 https://my.telegram.org/apps 获取 API 凭据

telegram auth                                # First-time login
telegram logout                              # Clear saved session
telegram check                               # Verify session is valid
telegram whoami                              # Show logged-in account
telegram whoami --json                       # Account info as JSON

📖 命令

读取消息
telegram inbox                               # Unread messages summary
telegram chats                               # List all chats
telegram chats --type group                  # Filter: user, group, supergroup, channel
telegram chats -n 200                        # List up to 200 chats
telegram read "ChatName" -n 50               # Read last 50 messages
telegram read "ChatName" --since "1h"        # Messages from last hour
telegram read "ChatName" --until "2h"        # Messages up to 2 hours ago
telegram read @username -n 20                # Read DM with user
telegram read 123456789 -n 10               # Read by chat ID
搜索
telegram search "query" --chat "ChatName"    # Search within chat
telegram search "query" --all                # Search all chats (global)
telegram search "query" -n 20               # Limit results
发送消息
telegram send @username "message"            # Send DM
telegram send "GroupName" "message"          # Send to group
telegram reply "ChatName" 12345 "response"   # Reply to message ID
联系人和群组
telegram contact @username                   # Get contact info
telegram members "GroupName"                 # List group members
telegram members "GroupName" -n 500          # Fetch up to 500 members
telegram admins "GroupName"                  # List admins only
telegram groups                              # List all groups
telegram groups --admin                      # Groups where you're admin
telegram kick "GroupName" @username           # Remove user from group
telegram promote "GroupName" @username        # Promote a member to admin
telegram promote "GroupName" @username --rank "Mod"  # Promote with a custom admin title
telegram promote "GroupName" @username --add-admins  # Allow them to add admins too
telegram transfer-owner "GroupName" @username # Hand over ownership (prompts for 2FA password)

transfer-owner 说明：

  • 不可撤销：你将降为普通管理员／成员，只有新所有者可以重新转让所有权。
  • 你的账号需要启用两步验证（云密码）；运行时会安全地提示你输入密码。
  • 仅适用于超级群组和频道——请先将基本群组转换为超级群组。
  • 目标对象必须已经是成员。Telegram 还会在新登录后约 24 小时内，以及设置／更改两步验证密码后约 7 天内阻止转让。
  • 系统会提示你重新输入群组名称以确认；传入 -y 可跳过确认。
静音
telegram mute "ChatName"                     # Mute forever
telegram mute "ChatName" -d 1h               # Mute for 1 hour
telegram mute @username -d 8h                # Mute DM for 8 hours
telegram mute "GroupName" -d 1d              # Mute for 1 day
telegram unmute "ChatName"                   # Unmute
文件夹
telegram folders                             # List all folders
telegram folder "Work"                       # Show chats in folder
telegram folder-add "Work" "ProjectChat"     # Add chat to folder
telegram folder-remove "Work" "ProjectChat"  # Remove chat from folder
同步／导出
telegram sync                                # Sync last 7 days to ./telegram-sync
telegram sync --days 30                      # Sync last 30 days
telegram sync --since "12h"                  # Sync messages from last 12 hours
telegram sync --until "2d"                   # Sync messages up to 2 days ago
telegram sync --all                          # Sync entire chat history (no time limit)
telegram sync --chat "ChatName"              # Sync specific chat only
telegram sync --output ~/exports             # Custom output directory
telegram sync --resume                       # Incremental: only fetch new messages
telegram sync --resume --all                 # Keep a complete archive up to date

增量同步（--resume）：

  • 在每个聊天的 .sync-meta.json 中记录上次同步的消息 ID
  • 后续运行时，仅获取比上次同步更新的消息
  • 将新消息追加到现有 Markdown 文件
  • 与 --all 搭配使用，以维护完整且最新的存档

📤 输出格式

大多数命令都支持多种输出格式：

标志使用场景
(default)便于阅读的终端输出
--json用于程序化处理的结构化 JSON
--markdown用于显示或导出的 Markdown 格式
telegram inbox --json                        # JSON format
telegram inbox --markdown                    # Markdown format
telegram read "Chat" --json                  # JSON with messages array
telegram read "Chat" --markdown              # Markdown with messages
telegram chats --json                        # JSON with chat list
telegram members "Group" --markdown          # Markdown member list

支持的命令： inbox、read、search、chats、members、groups、contact、whoami

📎 媒体元数据

包含媒体（照片、视频、文档、语音消息、贴纸等）的消息现在会显示元数据，而不是显示“（无文本）”：

媒体类型显示内容
照片[📷 Photo]
视频[🎥 Video (2.1 MB)]
文档[📎 report.pdf (540.0 KB)]
语音[🎤 Voice message]
音频[🎵 song.mp3 (3.2 MB)]
贴纸[😀 Sticker]
GIF[🎬 GIF]
位置[📍 Location]
联系人[👤 Contact]
投票[📊 Poll]

在 JSON 输出中，包含媒体的消息会带有 mediaType、fileName 和 fileSize 字段。

🤖 AI Agent 指南

将此 CLI 用作 AI Agent 时：

  • 处理数据（计数、筛选、提取）：使用 --json
  • 向用户展示内容：使用默认格式或 --markdown
  • 聊天识别：名称采用部分匹配（例如，"MetaDAO" 匹配 "MetaDAO Community"）；用户名必须以 @ 开头；也可以使用数字 ID
  • 读取操作无需确认，可以安全执行
  • 写入操作（send、reply、kick、promote、transfer-owner）应在执行前向用户确认
  • transfer-owner 不可撤销且需要交互（它会提示输入 2FA 密码并要求键入确认内容），因此无法在无人值守的情况下运行；未经明确指示，切勿代替用户编写脚本执行此操作
  • 速率限制：避免连续快速调用；Telegram API 有速率限制
  • 大型群组：对于非常大的群组，使用 -n 限制 members 输出
  • 完整存档：使用 telegram sync --all --chat "Name" 导出完整聊天记录
  • 保持存档更新：使用 telegram sync --resume 增量更新之前的导出内容
  • 媒体丰富的聊天：带有照片、视频和文件的消息现在会显示元数据，而不只是显示“（无文本）”

💡 示例

检查收件箱中的未读消息：

telegram inbox

读取群组中的近期消息：

telegram read "MetaDAO Community" -n 20

获取过去 2 小时内的消息：

telegram read "Project Chat" --since "2h"

搜索所有聊天中的某个主题：

telegram search "futarchy" --all

在特定聊天中搜索：

telegram search "deadline" --chat "Work Team"

发送消息：

telegram send @username "Hello, checking in!"

导出聊天的完整记录：

telegram sync --all --chat "Project Chat" --output ~/exports

增量更新现有导出内容：

telegram sync --resume --output ~/exports

按类型筛选聊天：

telegram chats --type channel --json

将用户踢出群组：

telegram kick "My Group" @spammer

将成员提升为管理员：

telegram promote "My Group" @trustedmember

将群组所有权转让给其他人：

telegram transfer-owner "My Group" @newowner

📝 备注

  • 聊天名称支持部分匹配（例如，"MetaDAO" 匹配 "MetaDAO Community"）
  • 用户名必须以 @ 开头（例如，@username）
  • 在任何接受聊天名称的位置都可以使用聊天 ID（数字）
  • 消息按时间倒序返回（最新的在前）
  • 时间标志（--since、--until）接受 "1h"、"30m"、"7d" 等格式
  • sync 命令会在输出目录中为每个聊天创建一个 Markdown 文件
  • 同步元数据（.sync-meta.json）可通过 --resume 实现增量同步
  • 每次请求都会缓存发送者名称，以加快同步速度（避免冗余 API 调用）
  • 消息会自动分页——大型聊天不会被静默截断

评论

支持 Markdown