mcp-telegram

一个通过用户 API (MTProto) 将 Claude 等 AI 助手连接到您的真实 Telegram 账号的 MCP 服务器。它不是机器人，而是以您的身份读取和发送消息。

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

Telegram API 服务条款：本项目使用 Telegram 用户 API。您必须从 my.telegram.org 获取您自己的 api_id 和 api_hash，并遵守 Telegram API 服务条款。滥用用户 API（垃圾信息、群发消息、抓取数据）可能导致您的账号被封禁。您需自行承担使用此工具的后果。

目录

• 功能

• 您可以做什么

• 与 chaindead/telegram-mcp 的对比

• 快速开始

• 客户端配置

• 配置参考

• 安全性

功能

附加功能：

• 发送文件和照片

• 在聊天之间转发消息

• 回复特定消息

• 从消息历史中下载照片和文档

• 按日期范围过滤历史记录 (since / until)

• 类型化对等引用 (user:ID, chat:ID, channel:ID) 以防止 ID 冲突

• 延迟对等解析 — 避免启动时的 FLOOD_WAIT 错误

• RPC 级别的全局速率限制

您可以做什么

连接后，您可以向 AI 助手询问以下内容：

查看消息

• “检查我未读的 Telegram 消息并给我一个摘要”

• “@alice 在过去 24 小时内写了什么？”

• “显示周一以来开发团队聊天中的消息”

回复与沟通

• “起草一条回复给 @bob 的最后一条消息 — 先不要发送”

• “发送‘听起来不错，我们下午 3 点见面’给 @alice”

• “回复项目聊天中 ID 为 1234 的消息，内容是我的反馈”

管理收件箱

• “将新闻频道的所有消息标记为已读”

• “我白名单中的哪些聊天有未读消息？”

• “下载设计聊天中今天消息里的照片”

研究与分析

• “查找过去一周内提到部署的所有消息”

• “总结昨天团队聊天中的讨论”

• “本月项目频道中分享了哪些文件？”

与 chaindead/telegram-mcp 的对比

快速开始

前置条件

• Go 1.26+

• 一个 Telegram 账号

• 从 my.telegram.org 获取的 API 凭据 (api_id 和 api_hash)

安装

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

预编译二进制文件 (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 (设置 > MCP 服务器 > 添加):

{
  "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 中的聊天才可访问，且仅限于您指定的权限。

支持的匹配模式：

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

如果同一个对等方匹配多个规则（例如同时通过 @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

如果您觉得本项目有用，请给它一个星标 — 这有助于其他人发现它。