tgread

一个只读的 Telegram MCP 服务器。让 Claude Code 读取你的频道、群组和私信——并且不提供任何写入途径。

./install.sh          # pinned venv + ~/.local/bin/tgread + MCP registration
tgread login          # api_id/api_hash, phone, code, 2FA
tgread status         # who am I, is the session live, are perms sane

为什么不用现成的那些

有一些不错的社区服务器——chigwell/telegram-mcp 有 1.5k star、30 位贡献者和严谨的发布纪律。写这个的原因不是不信任那些代码，而是自己写的真正收益在于工具暴露面和可审查性，而不是依赖数量。当进程持有一个 Telegram 会话，并向智能体投喂攻击者控制的文本时，这两点才是关键。

手写 MTProto 是鲁莽的——Telethon 就是加密、DC 迁移和重连逻辑本身。所以它保留。它之上的一切都是我们自己的。

Related MCP server: telegram-mcp-server

威胁模型

读取频道意味着攻击者选择的文本会进入一个持有 shell 的智能体——而且通常还有你已连接的其他一切：邮件、笔记、云凭证。这是这里的主要风险，而且这不是由谁来编写服务器就能解决的。选择一个没有写入面的服务器，是少数不依赖模型表现良好的缓解措施之一。

flowchart TD
    A["hostile channel post<br/>'ignore previous instructions…'"] --> B["tgread read_chat"]
    B --> C["UNTRUSTED envelope<br/>wrapped around every payload"]
    C --> D["agent context"]
    D --> E{"agent tries to act on it"}
    E -->|"send / delete / join"| F["no such tool exists<br/>tools/call → isError"]
    E -->|"raw TL request"| G["guard at _call → WriteBlocked"]
    E -->|"summarise for the user"| H["fine — this is the intended path"]
    style F fill:#1f6f43,color:#fff
    style G fill:#1f6f43,color:#fff

三层防护，按它们在遇到 bug 时能幸存的程度递增排列：

1. 不公布任何写入工具。 注入的指令没有任何可调用的东西。

2. 每个载荷都被包装在一个 UNTRUSTED CONTENT 横幅中，标明它是数据而非指令——包括聊天的标题和简介，这些同样受攻击者控制。

3. 传输守卫。 Telethon 将所有出站 TL 请求都经由 TelegramClient._call 汇聚（68 个内部调用点通过 await self(req) 到达它，而 __call__ 是一行委托）。ReadOnlyClient 覆盖了它。即使这个文件有 bug，仍然无法改动账户。

该守卫默认拒绝：除非 TL 类名以 Get/Search/Resolve/Check/Find 开头，或位于一个九项基础设施白名单中，否则请求一律被拒绝。三个读取形态的请求按名称被拒绝，因为它们有其他人可观察到的影响——GetMessagesViews (增加公开的浏览量计数)、GetBotCallbackAnswer (按下内联按钮)、GetInlineBotResults (以你的身份查询机器人)。嵌套请求也会被遍历，因此写入无法藏在允许的 InvokeWithLayer 包装器内。

flowchart LR
    R["TL request"] --> W["walk nested .query"]
    W --> D{"in EXPLICIT_DENY?"}
    D -->|yes| X["WriteBlocked"]
    D -->|no| I{"in INFRA_ALLOW?"}
    I -->|yes| P["to the wire"]
    I -->|no| V{"starts with Get/Search/<br/>Resolve/Check/Find?"}
    V -->|yes| P
    V -->|"no — incl. every<br/>name we've never seen"| X
    style X fill:#8b2020,color:#fff
    style P fill:#1f6f43,color:#fff

tgread check 可离线运行这些检查：26 个写入请求被阻止，17 个读取请求被允许，未知名称默认拒绝，嵌套已检查。无需网络、无需会话、无需凭证。

工具

这里刻意不提供媒体下载：获取附件意味着将攻击者选择的字节写入智能体的文件系统。消息元数据只报告媒体的类型。

操作说明

• 使用辅助账户。 用户机器人（任何非官方应用的 MTProto 客户端）都可能因违反服务条款而被封禁。这个风险对此处的每个服务器都一样。

• 会话文件是整个账户的持有者令牌。 更改 Telegram 密码并不会使其失效。只有 tgread logout——它会在本地删除前先在服务端撤销——或 设置 → 设备 才能使其失效。请像对待 SSH 私钥一样对待它。

• pip install telegram-mcp 不是这个，也不是 chigwell 的。 那个 PyPI 名称属于一个无关项目；向它传递 TELEGRAM_API_ID / TELEGRAM_API_HASH 会把你的凭证交给第三方代码。这里没有任何内容被刻意发布到 PyPI。

• 所有状态都存放在一个目录中——$TGREAD_STATE_DIR，默认为 ~/.local/state/tgread，权限 0700，其中包含 config.env (0600) 和 tgread.session (0600)。一个目录，方便 chmod、备份、销毁。如果权限发生漂移，tgread status 会标记出来。

• install.sh 使用 uv sync --frozen——它只安装已提交的 uv.lock 中的确切版本，宁可失败也不重新解析。一个会悄悄获取新上游版本的解析器，正是被攻陷的包进入持有你会话的进程的方式。

目录结构

命令

tgread login      interactive: API credentials, phone, login code, 2FA
tgread status     who am I, is the session valid, are permissions sane
tgread logout     revoke server-side, then delete locally
tgread check      offline self-test of the read-only guard
tgread serve      speak MCP over stdio — what Claude Code runs

login 和 logout 使用普通客户端，而不是受守卫的客户端：守卫的存在是为了约束智能体，而不是约束在终端建立或撤销会话的人类。MCP 服务器接触的一切都经由 ReadOnlyClient。