（4042期）telethon-plus – Telegram 用户账户的 HTTP 与 MCP 控制中枢

Telegram 用户账户的 HTTP 与 MCP 控制中枢 基于 Telethon 的 Docker 容器化方案，将真实 Telegram 用户账户封装为 HTTP/MCP 双协议 API，支持完整的读写管理操作与实时消息推送，适合自建自动化工作流。 使用说明 核心用法 telethon-plus 是一个将 Telethon（Telegram MTProto 用户协议客户端）包装为 HTTP API 和 MCP（Model Context Protocol）端点的容器化服务。与 Bot API 不同，它驱动的是完整的 Telegram 用户账户，具备读写、管理、管理员等全部权限。 主要能力包括： 消息操作：发送/编辑/删除/转发消息，支持 Markdown/HTML 解析，可回复、静默发送、定时调度 媒体处理：通过 URL 发送文件/图片，或下载消息中的附件（HTTP 流或 MCP base64） 对话管理：列出会话、解析用户名/手机号/t.me 链接、搜索历史消息 群组与频道：创建/删除/加入/离开，获取成员列表，解析关联讨论组 管理员功能：禁言/解禁/踢人/提升/降级管理员，支持细粒度权限控制 投票系统：创建投票、投票、查看结果 实时推送：通过 WebSocket 或 webhook (TELETHONPOSTTO_URL) 接收所有 incoming 事件 服务提供双入口：标准 REST API (/api/...) 和 MCP 流式 HTTP 端点 (/mcp/)，共 34 个工具，JSON 进出，Bearer Token 可选认证。 显著优点 完整用户账户权限：超越 Bot API 限制，可操作私密对话、获取完整成员列表、执行管理员命令 双协议兼容：既支持传统 HTTP/REST 调用，也支持 MCP 协议，便于接入 Claude 等 AI Agent 实时事件流：WebSocket 和 webhook 双重机制，适合构建消息机器人、通知中心、自动化工作流 内置防刷保护：多级令牌桶限流、自适应退避、实体缓存，主动规避 Telegram 的 FLOOD_WAIT 封禁 部署简单：单容器 Docker 部署，环境变量配置，健康检查与 Prometheus 指标开箱即用 灵活的实体引用：支持 @用户名、手机号、t.me 链接、数字 ID、me（收藏夹）等多种形式 潜在缺点与局限性 部署前提复杂：需要用户自行完成 Telegram 账户的首次登录（生成 session string），技能本身不处理登录流程 SSRF 攻击面：file_url 参数由服务端抓取，若接受不可信 URL 可能导致内网探测，需严格校验域名白名单 ID 解析限制：纯数字 ID 需先有访问记录（通过用户名解析或对话列表），冷 ID 无法直接解析 无多租户架构：每个容器绑定单一账户，不支持 Bot API 式的多机器人管理 数据外泄风险：启用 webhook 会将全部 incoming 消息转发至外部端点，需确保目标可信 资源占用：长期运行的 MTProto 会话与消息缓存需要持续内存和网络连接 适合的目标群体 开发者与运维工程师：需要将 Telegram 整合到自建系统、CI/CD 通知、监控告警的个人或团队 自动化爱好者：希望用脚本、curl 或 AI Agent 控制个人 Telegram 账户进行消息归档、内容转发、定时发布 社群管理员：管理大型群组/频道，需要批量执行禁言、踢人、权限调整等管理员操作 隐私优先用户：Bot API 无法满足需求（如获取完整成员列表、操作私密对话），且愿意自建基础设施 MCP 生态探索者：希望将 Telegram 作为工具链接入 Claude Code 等 MCP 兼容的 AI 环境 常规使用风险 | 风险类别 | 说明 ||---------|------|| 账户封禁 | 尽管有防刷机制，高频操作或违反 Telegram ToS（垃圾信息、批量拉人）仍可能导致账户受限或永久封禁 || 权限过大 | 完整账户访问意味着误操作可删除群组、清空消息、提升恶意用户为管理员，破坏性操作需二次确认 || 凭证泄露 | TELETHONAUTHKEY 和 session string 泄露等于账户完全失控，需严格保管 || 网络暴露 | 若将 /api/ 或 /mcp/ 暴露至公网且无认证，任何人均可操作账户，建议绑定 localhost 或配合反向代理 + TLS || 依赖可用性 | 服务依赖 Docker 容器持续运行，Telegram 服务器故障或网络中断会导致 API 不可用 || 数据隐私 | webhook 和 MCP 调用会将消息内容外发至配置的目标，需确认接收端的数据处理合规性 | 原始说明 HTTP + MCP control plane over a REAL Telegram MTProto userbot (Telethon) — a full user account, not the Bot API. Send/read/edit/delete/forward messages, browse dialogs, resolve entities/contacts, download + send media, manage chats (create/join/leave/admin), run polls, and forward every incoming message to a webhook (TELETHON_POST_TO_URL). JSON in / JSON out on one port; MCP streamable-HTTP at /mcp/ mirrors the same tools; optional bearer auth. Built-in anti-flood throttling keeps the account under Telegram's limits. Use when the user wants an agent, script, or curl one-liner to drive their own Telegram account over HTTP/MCP — read a chat, DM someone, post to a channel, react/pin, or pipe incoming DMs into an app. Drives a real account acting AS the user with full account access.