内容
align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/banner-dark.svg">
<img alt="secure-telegram-mcp — 您的所有 Telegram 账户，一个 AI 客户端一个作用域端点" src="./docs/banner-light.svg" width="100%">
</picture将 Claude、Cursor 或任何 MCP 客户端连接到 Telegram — 无需提供完整账户信息。**
[](https://www.npmjs.com/package/secure-telegram-mcp)
[](https://github.com/antonorlov/secure-telegram-mcp/actions/workflows/ci.yml)
*演示合成数据上 — 无实际 Telegram 连接，无可用凭证。div>
## ❌ 通常的 Telegram MCP 设置
- AI 客户端持有您的**完整账户会话** — 每个聊天联系人、每次写入。
- 访问是**全部或全：您的工作代理可以读取您的家庭群组。
- 会话凭证以**明文**存储在配置文件或 `.env` 中。
## ✅ 使用 secure-mcp
- 每个 AI 客户端都有一个**端点**：其自己的 API 密钥，限定于您选择的聊天和文件夹。
- **每次调用检查读/写动词**，并且会关闭失败工具菜单是发现，而不是- Telegram 会话**加密**（AES-256-GCM，scrypt 包装密钥），默认机器绑定或 PIN 保护。
例如：
| AI 客户端 | 端点 | 账户 | Telegram 范围 | 访问权限 |
| --- | --- | --- | --- | --- |
| 个人代理 | `personal` | `main` | 私人聊天 | 读取 + 写入 |
| 工作代理 | `work` | `work-acc` | `工作` 文件夹 | 只读 |
每个 MCP 连接都验证一个端点，并为该端点的账户接收一个范围绑定的 Telegram 适配器。端点可以绑定不同的已登录账户；同一个账户上的端点共享一个后台 Telegram 连接。超出范围的聊天无法访问。
## 功能
- 🔑 **每个端点的 API 密钥** — 每个 AI 客户端都有其自己的密钥和范围，绑定到您的一个已登录账户（一个或多个）；仅存储盐化密钥哈希。
- 📁 **文件夹范围访问** — 将端点绑定到 Telegram 文件夹、聊天或频道；写入访问权限按端点可选。
- 🔒 **静止加密会话** — 会话和策略的 AES-256-GCM 信封；PIN、恢复密钥文件和机器绑定解锁槽。
- 🚦 **反封禁节奏** — 每个、转发和搜索都有令牌桶，以及一个电路中断器，在账户饱和的第一个迹象时关闭。节奏降低了洪水限制的风险；无法保证不会被封禁。
- 👤 **人工干预写入** — 可选的每个端点确认；需要支持 MCP 诱导的客户端。对于不支持的客户端，确认写入端点会关闭：写入被阻止，从不静默。
- ⛔ **无原始 MTProto 接口** — 无 `invoke` 出口，无模型可访问的范围突变；CI 架构守护进程使其保持这样。
## 快速入门
**先决条件：** Node.js ≥.10 和来自 [my.telegram.org/apps://my.telegram.org/apps) 的 Telegram `api_id`/`api_hash`。
### 1. 运行设置
```bash
npx -y secure-telegram-mcp setup
```
设置按顺序进行：
1. **Telegram 应用凭证** — 来自先决条件的 `api_id` / `api_hash`。
2. **登录方法** — 二维码（从已登录的手机扫描）或电话号码 + 代码。如果您的账户有两步验证，设置还会询问该密码。
3. **会话名称** — 按 Enter 接受建议（您的 Telegram 用户名，如果没有则为 `main`）。
4. **PIN 或无 PIN** — 默认无 PIN（加密密钥此机器，无需解锁）。使用 PIN 时，您在每次重启后重新输入它；忘记 无法恢复。
5端点** — 命名，然后在选择器中选择聊天/文件夹：`r` 或空格授予读取权限，`w` 写入权限，`s` 保存，`?` 显示完整按键映射。
，端点的 API 密钥打印**一次**，在准备粘贴的客户端配置中关闭终端之前复制它。遇到问题？请参阅[故障排除](./docs/USAGE.md#troubleshooting)。
### 2. 将端点添加到 *一个* MCP 客户端
```json
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "secure-telegram-mcp", "connect"],
"env": {
"TELEGRAM_MCP_ENDPOINT_TOKEN": "tgmcp_..."
}
}
}
}
```
令牌本身选择并授权端点 — 客户端配置中永远不会出现 `api_id`、`api_hash` 或 PIN 材料。设置打印每个端点的块；每个块仅进入其自己的客户端 — 故意在客户端中组合条目会授予其范围的并集。
<details>
<summary><b>Claude 代码</b></summary>
```bash
claude mcp add telegram --env TELEGRAM_MCP_ENDPOINT_TOKEN=tgmcp_... -- npx -y secure-telegram-mcp connect
```
</details>
<details>
<summary><b>Claude 桌面版</b></summary>
将上面的 JSON 块添加到 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）。
</details>
<details>
<summary><b>Cursor</b></summary>
[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="在 Cursor 中安装" height="28">](https.com/en/install-mcp?name=telegram&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIIsInNlVyZS10ZWxlJhbS1tY3AiLCJjb25uZWN0Il0sImVudiI6URUxFR1JBTV9NQ1BfRU5EUE9JTlRfVE9LRU4iOiJ0Z21jcQQVNURV1VSX0VORFBPSU5UXPS0VOIn19)
运行设置后，点击并替换占位符令牌 — 或将上面的 JSON 块添加到/.cursor/mcp。
</details>
<detailssummary><b>VS Code</b></summary>
[](https://insscode.dev/redirect/mcp/install?name=telegram=%5B%7B%22type%22%%22promptString%22%2C%22id%22%3A%22endpoint_token%22%%22description%22%3A%22由设置打印的端点令牌（tgmcp_...22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%%22npx%2C%22args%3A%%22-y%2C%22secure-mcp%22%222connect%5D%222env%22%3A%7B%22TELEGRAM_MCP_ENDPOINT22%3A%22%24%7B3Aendpoint_token%7D%22%7D%7D)
VS Code 提示输入端点令牌作为掩码秘密 — 它永远不会出现在其他扩展建议的设置文件中。
</details>
<summary><b>Docker</b></summary>
参见[用法和操作](./docs/USAGE.md#docker)，了解设置和 stdio-connect 容器。
</details>
### 3. 解锁（仅限 PIN 姿势）
如果您保留了默认的机器绑定保护，请跳过此步骤 — 服务在客户端连接时自动启动。使用 PIN：
```bash
npx -y secure-telegram-mcp start
```
交互式输入 PIN；客户端永远不需要它。多客户端示例、自动解锁、环境变量和手动策略编辑都在[用法和操作](./docs/USAGE.md)中。
## 工具
18，由 8 种词控制，在进行检查。
| 类别 | 工具 | 动词 |
| --- | --- | --- |
| 读取 | `get_messages`、`search_messages`、`list_dialogs`、`list_topics`、`get_chat、`get_media_infoget_pinned_messages`_participants` | `read` |
| | `download_media`（严格的大小限制，服务器选择的目录） | `read_media` |
| 发送和编辑send_message`、``、`prepare_media`、`send_media` | `send` |
| 其他写入 | `save_draft`_message`、`mark_read`、`send_reaction`、`forward | `draft`、`delete`、`mark、`react`、` |
转发是双：源聊天中的 `read` *和* `forward`。发送本地媒体是一个刻意的两 — `prepare_media` 返回一个不透明的期的文件句柄，位于受限的媒体根；`send_media` 消耗它。完整的目录和动词语义在[用法和操作](./docs.md#tool-catalog中。
## 安全模型
- 一个本地服务的 Telegram 会话和策略；MCP 垫片永远不会打开 会话。
- 每次调用都会重新验证端点令牌与当前密封策略，因此轮换密钥会连接失效。
- 没有原始的 MTProto 工具模型可以扩大其自身范围的方法。
- ACL → 可选的人工确认 → 配额 →，按此顺序，并关闭每个关口的失败 Telegram 文本在到达模型之前进行 Unicode 净删除控制/格式字符，限制长度） ；拒绝和媒体出口记录在只追加的 NDJSON 审计日志中。
- **已知限制：** 是您的本地 OS 用户；端点 ACL 无法缩小底层完整账户会话如果进程本身被泄露；净化无法消除语义提示注入。
只读端点尝试 `send_message` 在 ACL 门处停止并被审计 — 一行 NDJSON，无消息内容：
```json
{"v":1,"timestampIso":"2026-07-17T09:41:22.310Z","endpointName":"work","verb":"send","outcome":"deny","targetChatId":"-1001234567890","reason_NOT_GRANTED"}
```
客户端一个 `ACL_DEN 错误。超出范围的对等方也会以相同的方式拒绝，带有 `PEER_OUT_OF_SCOPE`将此指向您关心的 Telegram 账户之前，请[威胁模型](./SECURITY.md) — 包括非目标和剩余风险。组件边界在[架构](./ARCHITECTURE.md)中。
## 文档
- [用法和操作](./docs/USAGE.md) — 客户端、端点、命令、环境变量、Docker、媒体、工具目录。
- [安全](./SECURITY.md) — 威胁模型、保证、剩余风险、强化部署。
- [架构](./ARCHITECTURE.md) — 进程所有权、信任边界、策略生命周期。
- [示例配置](./telegram-mcp.config.example.json) — 模式有效、故意不可用的占位符。
## 开发
```bash
npm run ci # 类型检查 + lint + 架构守护进程 + knip + 测试
npm run build
```
架构守护进程拒绝禁止的 MCP 接口和未经审查的 MTProto 请求构造函数；ESLint 强制执行，并将 GramJS 限制在基础设施层。请 PR 之前阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
<!-- TODO: uncomment when wanted
## 星历史
[](https://star-history.com/#antonorlov/secure-telegram-mcp&Date)
如果这个项目对您有帮助，⭐ 帮助其他人找到它。
-->
##
[MIT](./LICENSE)
---
*非官方项目：不隶属于、不支持、不赞助 Telegram FZ-LLC。
"Telegram" 是 Telegram FZ-L商标。本软件连接到 Telegram API；
每个用户都提供自己的 API 凭证。*
