telegram-mcp

将某个 Telegram 群组中的最新图片交给 Claude。

这些截图由机器人发布，而 Telegram Bot API 永远不会返回机器人自己的消息——所以这里通过 MTProto（Telethon）使用 用户 账户读取群组。这是看到这些照片的唯一方式。

一次性设置

1. 从 https://my.telegram.org → API 开发工具获取 API ID 和哈希值。

2. 执行 cp .env.example .env 并填写 TELEGRAM_API_ID、TELEGRAM_API_HASH 和 TELEGRAM_CHAT_ID（群组的数字 ID，取负数）。

3. 创建环境：

   python -m venv .venv
   .venv\Scripts\pip install -e .[dev]

4. 在终端中登录，而不是通过 Claude：

   .venv\Scripts\telegram-mcp-login

   它会要求你输入手机号码、Telegram 发送的验证码，以及（如果有）两步验证密码，然后写入 session/telegram.session。

   它还会列出你的对话框一次，并把群组名称回显给你。列表功能让会话此后能够解析出超级群组——Telegram 会在机器人加入群组后立即把它升级为超级群组——而这个名称正是你确认 TELEGRAM_CHAT_ID 指向预期位置的依据。如果找不到该群组，它会明确说明并以非零状态退出。

Related MCP server: telegram-user-mcp

安装到 Claude

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

用户级作用域，因此每个项目都能使用。

工具

• get_latest_image() — 返回群组中的最新图片，最多回看 200 条消息。

• wait_for_next_image(timeout_seconds=120) — 阻塞，直到有比调用时刻更新的图片到达。等待不消耗令牌；进程在 socket 上空闲等待。限制在 1–240 秒，以确保不超出 MCP 客户端的工具超时。

两者都返回图片（JPEG，长边 ≤1568 像素）和一行文本：先是原始图片的路径，然后依次是消息 ID、时间戳、发送者和带引号的说明文字。当缩放后的小字细节丢失时，请裁剪原始图片。

同一时间只能有一个进程持有该会话。当第一个 Claude Code 会话正在调用时，第二个会话若调用工具会被告知稍后重试，而不是收到 SQLite 错误。

测试

.venv\Scripts\python -m pytest

无需网络，也无需 Telegram 账户——Telethon 全程被模拟。

安全

session/telegram.session 是你 Telegram 账户的完整登录凭据。它已被 gitignore，且永远不会离开这台机器。任何持有该文件的人都能读取你的消息；如果你怀疑它已被复制，请删除它并重新登录。凭据只存在于 .env 中——绝不要出现在文档、提示词或工单中。