Mcp Telegram

mcp-telegram

一个 MCP 服务，通过 User API（MTProto）将 Claude 等 AI 助手连接到你的真实 Telegram 账户。它不是机器人——Claude 会以你的身份读取和发送消息。

基于 gotd/td 和官方 MCP Go SDK 构建。

Telegram API 服务条款：本项目使用 Telegram User API。你必须从 my.telegram.org 获取自己的 api_id 和 api_hash，并遵守 Telegram API 服务条款。滥用 User API（垃圾消息、群发消息、抓取数据）可能导致你的账户被封禁。你须对如何使用此工具承担全部责任。

目录

• 功能
• 你可以用它做什么
• 与 chaindead/telegram-mcp 的比较
• 快速开始
• 客户端配置
• 配置参考
• 安全

---

功能

工具	功能	所需权限
tg_me	返回当前账户信息	—
tg_dialogs	列出 ACL 白名单可见的对话	—
tg_history	获取消息历史，支持分页、日期筛选和媒体下载	read
tg_search	按文本查询搜索聊天中的消息，可选按发送者筛选	read
tg_send	发送文本消息或文件，可选回复指定消息	send
tg_forward	将消息从一个聊天转发到另一个聊天	read + send
tg_draft	保存草稿消息（不会发送）	draft
tg_mark_read	将聊天标记为已读	mark_read

其他功能：

• 发送文件和照片
• 在聊天之间转发消息
• 回复指定消息
• 从消息历史中下载照片和文档
• 按日期范围筛选历史记录（since / until）
• 使用类型化对等方引用（user:ID、chat:ID、channel:ID）防止 ID 冲突
• 延迟解析对等方——避免启动时出现 FLOOD_WAIT 错误
• 在 RPC 层进行全局速率限制

你可以用它做什么

连接后，你可以向 AI 助手提出以下请求：

查看未读消息

• “查看我未读的 Telegram 消息并总结一下”
• “@alice 在过去 24 小时内写了什么？”
• “显示 Dev Team 聊天中从周一开始的消息”

回复和沟通

• “为 @bob 的最后一条消息拟一份回复——先不要发送”
• “给 @alice 发送‘听起来不错，我们下午 3 点见’”
• “在项目聊天中回复消息 1234，附上我的反馈”

管理收件箱

• “将新闻频道中的所有消息标记为已读”
• “我的白名单聊天中，哪些有未读消息？”
• “下载今天设计聊天中的照片”

研究和分析

• “查找过去一周所有提到部署的消息”
• “总结昨天团队聊天中的讨论”
• “本月项目频道分享了哪些文件？”

---

与 chaindead/telegram-mcp 的比较

	mcp-telegram	chaindead/telegram-mcp
访问控制	默认拒绝的 ACL 白名单，支持细粒度的单聊权限	可完全访问所有聊天
Peer 寻址	类型化引用（user:ID、chat:ID、channel:ID）	仅支持数字 ID（容易发生冲突）
配置	支持环境变量展开的 YAML 配置	CLI 标志
启动安全性	延迟解析 Peer（不批量调用 API）	急切解析（有 FLOOD_WAIT 风险）
速率限制	内置令牌桶中间件	无
文件支持	发送文件和照片；从历史记录下载媒体	仅支持文本
回复支持	支持	不支持
日期筛选	支持	不支持

---

快速开始

前提条件

• Go 1.26+
• Telegram 账号
• 来自 my.telegram.org 的 API 凭据（api_id 和 api_hash）

安装

Homebrew（macOS / Linux）：

brew install Prgebish/tap/mcp-telegram

NPX（无需安装）：

npx @prgebish/mcp-telegram serve --config config.yaml

预编译二进制文件（macOS / Linux / Windows）：

从 GitHub Releases 下载。

Go 安装：

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

从源代码构建：

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

这会在当前目录中生成 mcp-telegram（Windows 上为 mcp-telegram.exe）。

身份验证

运行一次身份验证命令以创建会话文件。系统会提示你输入电话号码、登录验证码，以及（如果已启用）2FA 密码。

macOS / Linux：

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows（PowerShell）：

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows（cmd）：

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

配置

创建一个 config.yaml：

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

加载时会展开 ${...} 语法的环境变量。

客户端配置

服务通过 stdio 通信——MCP 客户端会启动并管理该进程。

Claude Code（CLI — 使用命令添加）：

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code（~/.claude.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor（Settings > MCP Servers > Add）：

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

---

配置

ACL

ACL 为默认拒绝。只有明确列在 acl.chats 中的聊天才可访问，且仅拥有你指定的权限。

支持的匹配模式：

模式	示例	说明
@username	@johndoe	按 Telegram 用户名匹配（不区分大小写）
+phone	+79001234567	按电话号码匹配
user:ID	user:123456789	按数字 ID 匹配用户
chat:ID	chat:987654321	按数字 ID 匹配群聊
channel:ID	channel:2225853048	按数字 ID 匹配频道或超级群组

权限类型：read、send、draft、mark_read。

如果同一 Peer 匹配多条规则（例如通过 @username 和 user:ID 匹配），权限会合并，不会相互覆盖。

速率限制

limits.rate 部分用于配置全局令牌桶，以限制所有 Telegram RPC 调用：

• requests_per_second — 持续速率（默认值：2.0）
• burst — 最大突发请求数（默认值：3）

媒体下载

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

配置后，tg_history 会自动将媒体文件下载到指定目录。download_to 参数可覆盖该路径，但仅限于 media.directory 或其子目录。

allowed_upload_dirs 用于限制 tg_send 可读取文件的目录。除非配置此项，否则文件发送功能会被禁用。

---

安全性

• 默认拒绝的 ACL — 除非明确加入白名单，否则无法访问任何聊天
• 文件系统边界 — tg_send 只能读取 allowed_upload_dirs 中的文件；download_to 限定在 media.directory 的子目录内
• 会话文件权限 — 强制设为 0600（仅所有者可读写）
• 不记录密钥 — API 哈希、会话令牌和身份验证密钥绝不会写入日志
• 不暴露访问哈希 — 所有工具输出都会剔除内部 Telegram 访问哈希
• 速率限制 — 防止意外滥用 API
• 本地时区 — 日期筛选使用你的系统时区，而非 UTC

---

许可证

MIT

---

如果你觉得这个项目有用，请给它点个星标，帮助更多人发现它。