tdl-mcp

tdl-mcp

借助 tdl 命令行工具，为 Claude 和其他 MCP 主机提供只读的 Telegram 访问能力。

使用五个简单的工具，即可通过你自己的 Telegram 账户列出聊天、读取近期消息和下载媒体文件。它绝不会发送消息、修改任何内容，也不会触碰你的登录状态。

🇰🇷 한국어 문서는 여기 있습니다 → README.ko.md

为什么选择 tdl-mcp？

大多数 Telegram MCP 服务都会内置一个 MTProto 库（Telethon、gramjs 等），要求你前往 my.telegram.org 创建自己的 Telegram 应用以获取 api_id/api_hash，而且其中许多都能代你发送消息。

tdl-mcp 则采用了另一种刻意保持简单的方案：

• 设计上只读。 服务可以列出聊天、导出消息和下载文件，仅此而已。代码中没有任何发送、编辑、删除或登录的路径。
• 无需配置 api_id/api_hash。 你只需在终端中通过 tdl login -T qr 登录一次，用手机扫描二维码即可。无需注册 Telegram 应用。
• 基于经受过实战考验的下载工具。 tdl（7.5k+ ⭐）负责繁重工作：快速并行下载、断点续传以及 --skip-same 去重。
• 轻量且易于审查。 一个纯 JavaScript 文件，两个依赖项（@modelcontextprotocol/sdk、zod），无需构建步骤。五分钟即可读完整个服务。

Claude / MCP host  ←stdio→  tdl-mcp (Node)  →subprocess→  tdl CLI  →MTProto→  Telegram

快速开始

1. 安装 tdl

# macOS
brew install telegram-downloader

# Linux / WSL
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash

# Windows (PowerShell)
iwr -useb https://docs.iyear.me/tdl/install.ps1 | iex

使用不低于 .tdl-version 中固定版本的任意版本都应该可以正常运行——CI 会持续针对该固定版本进行测试（参见兼容性与保持最新）。

2. 登录 Telegram（仅需一次）

tdl login -T qr

使用 Telegram 移动应用扫描二维码（设置 → 设备 → 关联桌面设备）。会话保存在你机器上的 ~/.tdl 中，并由每个 MCP 主机共享——你只需登录一次。tdl-mcp 本身绝不会执行或刷新登录。

3. 将服务添加到 MCP 主机

你需要 Node.js ≥ 22。

Claude Code：

claude mcp add --scope user telegram -- npx -y tdl-mcp

Claude Desktop / 任何其他 MCP 主机（通用 mcpServers JSON）：

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tdl-mcp"]
    }
  }
}

4. 试用

可以向你的助手提出以下请求：

“我有哪些 Telegram 聊天？找出与量化交易有关的那个。”

“显示 @some_channel 中最近的 20 条消息。”

“将该频道中从消息 1500 开始发布的所有 PDF 下载到 ~/Papers。”

如果某个工具提示你尚未登录，请在终端中运行 tdl login -T qr 并重试——这是唯一需要手动执行的步骤。

工具

工具	参数	功能
tg_status	—	检查 tdl 会话是否已登录。永不报错：返回 {logged_in:true, chats:N} 或 {logged_in:false, hint}。
tg_chats	filter?	列出对话，格式为 [{id, type, name, username}]；filter 会按名称、用户名或 ID 进行不区分大小写的子串匹配。
tg_messages	chat、last_n?（默认 50，最大 500）、since_id?、with_text?（默认 true）	将对话中的近期媒体消息导出为紧凑的 {id, date, file, text} 对象（最多返回 200 条；截断时会注明）。since_id 仅获取已知 ID 之后的消息，便于增量读取。
tg_download	chat、since_id?、last_n?（默认 100）、extensions?（csv，例如 "xlsx,pdf"）、dest?（默认 ~/Downloads/telegram）	使用 --skip-same 从对话中下载媒体；返回新下载文件的绝对路径，若没有匹配文件，则返回友好的提示。
tg_download_url	urls（https://t.me/... 链接数组）、extensions?、dest?	通过链接下载指定消息中的媒体。会验证每个 url 是否以 https://t.me/ 开头。

chat 可以是数字 ID，也可以是 @username/域名，格式与 tg_chats 显示的完全一致。

环境变量

变量	作用
TDL_BIN	tdl 二进制文件的路径。默认使用 PATH 中的 tdl；若找不到，则使用 /opt/homebrew/bin/tdl（通过 GUI 启动的 MCP 宿主通常无法继承 Homebrew 的 PATH）。
TDL_NS	tdl 命名空间，每次调用时都会作为 -n <ns> 传入。可用于区分不同的 Telegram 账号/会话。

在宿主的服务配置中设置这些变量，例如：

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tdl-mcp"],
      "env": { "TDL_NS": "work" }
    }
  }
}

兼容性与保持更新

tdl-mcp 会通过命令行调用 tdl CLI，因此它真正依赖的是 tdl 的 命令行接口。该接口会自动受到以下检查的保护：

• .tdl-version 固定了本软件包经过测试所用的 tdl 版本。
• scripts/contract.mjs 会在不登录的情况下验证服务端使用的所有标志（chat ls -o json、chat export -c/-T/-i/-o/--with-content、dl -f/-u/-i/-d/--skip-same、全局 -n） 在该 tdl 二进制文件中仍然存在。CI 会在每次推送和 PR 时运行该检查。
• 定时工作流会监视 tdl 发布。 有新版本时，它会使用新二进制文件运行契约测试，并扫描发布说明中的破坏性变更标记。 常规更新只需提交简单的版本升级 PR；任何可疑情况都会升级为 AI 辅助的升级 PR，以调整封装代码。

因此，如果你使用的 tdl 版本比固定版本更新，一切正常运行的可能性很高； 即使出现问题，本仓库也会先于你发现。

开发

git clone https://github.com/rixile9999/tdl-mcp.git
cd tdl-mcp
npm install
npm test          # smoke (MCP protocol, login-free) + contract (tdl CLI surface)

• npm run smoke 会通过 stdio 启动服务，并检查工具目录、tg_status 的结构和输入验证；无论你是否已登录，都会通过。
• npm run contract 会根据服务端使用的 CLI 接口检查已安装的 tdl 二进制文件。如果你想针对其他版本进行测试，可以使用 scripts/install-tdl.sh [vX.Y.Z] 安装特定的（经过校验和验证的）tdl 版本。

欢迎提交 PR。请确保服务保持只读；发送、编辑或删除内容的工具不在本项目范围内。

安全说明

• ~/.tdl 中的 tdl 会话属于完整的用户账号凭证——任何能读取它的人都可以操作你的 Telegram 账号。请像保护 SSH 密钥一样保护它：不要将它复制到代码仓库、共享备份或其他机器中。
• tdl-mcp 从不读取或传输会话本身；它只会在本地运行 tdl 二进制文件。除 tdl 自身的 Telegram 流量外，没有任何内容会离开你的机器。
• 下载内容会保存到你选择的目录（dest），默认目录为 ~/Downloads/telegram。

Telegram 服务条款说明

tdl 驱动的是常规用户会话（MTProto），而不是机器人。通常，安静、只读地自动化使用自己的账号不会有问题，但过度抓取可能导致账号受限：保持范围适中（last_n、since_id），避免大量并行拉取，并让 --skip-same 发挥作用，而不是重复下载。

许可证

本仓库中的所有内容均采用 MIT 许可证。

tdl 本身是一个独立项目，采用 AGPL-3.0 许可证。tdl-mcp 不会打包、链接或修改 tdl，而是将你安装的二进制文件作为独立进程调用，因此 AGPL 适用于 tdl，而非此封装程序。你需要通过官方渠道自行安装 tdl（见上文第 1 步）。