Secure Telegram

连接 Claude、Cursor 或任何 MCP 客户端到 Telegram，无需向它们开放你的完整账号。

演示使用合成数据运行，不会连接真实的 Telegram，也不会生成可用凭据。

❌ 常见的 Telegram MCP 配置方式

• AI 客户端持有你的完整账号会话——可以访问每个聊天、每个联系人，并执行所有写入操作。
• 访问权限非全即无：工作 Agent 可以读取你的家庭群组。
• 会话凭据以明文保存在配置文件或 .env 中。

✅ 使用 secure-telegram-mcp

• 每个 AI 客户端都有一个端点：拥有自己的 API 密钥，并受限于你选择的聊天和文件夹。
• 每次调用都会重新检查读写操作，并在无法确认时默认拒绝——工具菜单用于发现工具，而非授予权限。
• Telegram 会话采用静态加密（AES-256-GCM，使用 scrypt 封装密钥），默认绑定到设备，也可通过 PIN 保护。

例如：

每个 MCP 连接都通过一个端点密钥进行身份验证，并获得绑定到该端点账号的 Telegram 适配器；没有密钥的客户端只能列出工具。不同端点可以使用不同的已登录账号；同一账号上的端点则共用一个后台 Telegram 连接。完全无法访问未授权范围内的聊天。

功能

• 🔑 每个端点使用独立的 API 密钥——每个 AI 客户端都有自己的密钥和访问范围，并绑定到你的一个或多个已登录账号；仅存储加盐后的密钥哈希。
• 📁 按文件夹限制访问范围——将端点绑定到 Telegram 文件夹、聊天或频道；每个端点的写入权限均需明确启用。
• 🔒 静态加密的会话——会话和策略使用 AES-256-GCM 信封加密；支持通过 PIN、恢复密钥文件和设备绑定方式解锁。
• 🚦 防封号节流——对每个账号的消息、转发和搜索使用令牌桶限流，并配有断路器，一旦出现过载迹象便暂停整个账号。节流可以降低触发洪泛限制的风险，但无法保证不会被封号。
• 👤 写入操作需人工确认——可选择按端点启用确认；需要客户端支持 MCP elicitation。对于不支持的客户端，启用了写入确认的端点会默认拒绝：阻止写入，绝不静默放行。
• ⛔ 不提供原始 MTProto 接口——没有 invoke 逃生通道，也不允许模型修改访问范围；CI 架构守卫会确保这一点。

快速开始

**前置条件：**Node.js ≥ 20.10，以及从 my.telegram.org/apps 获取的 Telegram api_id/api_hash。

1. 运行设置

npx -y secure-telegram-mcp setup

设置流程将依次引导你完成以下步骤：

1. Telegram 应用凭据 — 前置条件链接中提供的 api_id / api_hash。
2. 登录方式 — 二维码（用已登录账号的手机扫描）或手机号 + 验证码。如果你的账号启用了两步验证，设置流程还会要求输入该密码。
3. 会话名称 — 按 Enter 接受建议值（你的 Telegram 用户名；如果没有，则为 main）。
4. PIN 或不设 PIN — 默认不设 PIN（使用此机器作为加密密钥，无需解锁）。如果设置 PIN，每次重启后都需要重新输入；忘记 PIN 后无法恢复。
5. 端点 — 为其命名，然后在选择器中选择聊天/文件夹：r 或 Space 授予读取权限，w 授予写入权限，s 保存，? 显示完整按键映射。

退出时，端点的 API 密钥会在可直接粘贴的客户端配置中仅显示一次 — 关闭终端前请复制。遇到问题？请参阅故障排除。

2. 将端点添加到一个 MCP 客户端

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "secure-telegram-mcp", "connect"],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "tgmcp_..."
      }
    }
  }
}

仅凭令牌即可选择端点并获得授权 — 客户端配置中绝不会包含 api_id、api_hash 或 PIN 材料。设置流程会为每个端点打印一个配置块；每个配置块只能添加到对应的客户端 — 在一个客户端中合并多个配置项会有意授予该客户端这些权限的并集。

claude mcp add telegram --env TELEGRAM_MCP_ENDPOINT_TOKEN=tgmcp_... -- npx -y secure-telegram-mcp connect

3. 解锁（仅适用于设置了 PIN 的情况）

如果你保留了默认的机器绑定保护，请跳过此步骤 — 客户端连接时服务会自动启动。若设置了 PIN：

npx -y secure-telegram-mcp start

请交互式输入 PIN；客户端无需使用它。多客户端示例、无人值守解锁、环境变量和手动编辑策略的说明，参见使用与运维。

工具

18 个工具，由 8 种权限动词控制，并在执行时进行检查。

转发需要两端授权：源聊天需要 read 权限，目标聊天需要 forward 权限。发送本地媒体采用有意设计的两阶段流程：prepare_media 会返回一个不透明且会过期的句柄，该句柄对应受限媒体根目录中的文件；send_media 会使用该句柄。完整的工具目录和动词语义请参阅用法与操作。

安全模型

• 一个本地服务负责管理加密的 Telegram 会话和封存的策略；MCP 适配层不会另行开启 Telegram 会话。
• 每次调用都会根据当前封存的策略重新验证端点令牌，因此轮换密钥会撤销现有连接。
• 没有原始 MTProto 工具，模型也无法扩大自身权限范围。
• 写入操作依次经过 ACL → 可选的人工确认 → 配额 → 审计，并且在每个关卡都会以默认拒绝的方式处理失败。
• Telegram 文本在到达模型前会经过 Unicode 清理（剥离控制字符和格式字符，并限制长度）；写入操作、拒绝操作和媒体外发都会记录在仅追加的 NDJSON 审计日志中。
• **已知限制：**执行边界是你的本地 OS 用户；如果进程本身遭到入侵，端点 ACL 无法缩小底层完整账户会话本身所能执行的操作范围；清理也无法消除语义层面的提示注入。

只读端点尝试调用 send_message 时，会在 ACL 关卡被拦截并记录审计——仅产生一行 NDJSON，不含消息内容：

{"v":1,"timestampIso":"2026-07-17T09:41:22.310Z","endpointName":"work","verb":"send","outcome":"deny","targetChatId":"-1001234567890","reason":"VERB_NOT_GRANTED"}

客户端只会看到 ACL_DENIED 错误。对不在权限范围内的对象也会以相同方式拒绝，并返回 PEER_OUT_OF_SCOPE。

在将此工具用于你重视的 Telegram 账户之前，请阅读完整的威胁模型，其中包括非目标和剩余风险。组件边界请参阅架构。

文档

• 用法与操作 — 客户端、端点、命令、环境变量、Docker、媒体和工具目录。
• 安全 — 威胁模型、保证、剩余风险和强化部署。
• 架构 — 进程所有权、信任边界和策略生命周期。
• 示例配置 — 符合架构的配置，使用了刻意设置为不可用的占位符。

开发

npm run ci     # typecheck + lint + architecture guard + knip + tests
npm run build

架构守卫会拒绝被禁止的 MCP 接口和未经审查的 MTProto 请求构造器；ESLint 会强制执行依赖边界，并将 GramJS 限定在基础设施层。提交 PR 前请参阅 CONTRIBUTING.md。

许可证

MIT

非官方项目：与 Telegram FZ-LLC 无关联，也未获其认可或赞助。 “Telegram”是 Telegram FZ-LLC 的商标。本软件连接 Telegram API； 每位用户需提供自己的 API 凭据。