中文： Telegram MCP：复用你本机已登录的账号读取频道、群、私聊与联系人卡片，并提供受保护的 send_message / join_chat 写操作。发送默认做精确文本去重；不提供编辑或删除消息。 英语： README.en.md

---

快速启动

1.安装

2.一次性登录 + 自检

首次运行会自动：

• 使用 Telegram 个人账号登录（非 Bot Token）;按提示输入手机号、验证码，若开启 2FA 再输入密码。
• 创建或复用 ~/.tg-reader-mcp/tg_session.session，并收紧本地文件权限。
• 做一次只读 dialog 拉取自检，确认 session 可用。
• 输出 Claude Desktop 可直接复制的 JSON 和 Claude Code 可直接执行的命令;session 与可执行文件路径都已展开，无需手填绝对路径。

默认 API_ID / API_HASH 与 Telegram Desktop 公开凭据一致。若要使用自己的应用凭据，可先在 my.telegram.org 申请，然后运行：

如果直连 Telegram 失败，可用 TG_PROXY_URL（支持 http://``socks5://、socks4://）：

初始化时显式设置的 TG_API_ID、TG_API_HASH、TG_PROXY_URL 会自动带进生成的 MCP 配置，避免首次登录与后续运行使用不同参数。

3.接入 MCP 客户端

• Claude Desktop： 将 tg-reader-init 输出的 tg-reader 条目合并到现有 mcpServers 对象，然后重启 Claude Desktop。
• Claude Code： 直接运行 tg-reader-init 输出的 claude mcp add ... 命令。

---

Tools（与源码一致）

以下名称与 server.py 中 @server.list_tools() 注册项一一对应。

download_media

• 用途： 显式下载某条 Telegram 消息附带的 photo / image / video / document 到本地路径;远端只读。
• 参数： channel（必填）、message_id（必填）out_dir（可选，默认 ~/.cache/tg-media）。
• 示例：

list_dialogs

tg-reader-mcp

中文： Telegram MCP：复用你本机已登录的账号读取频道、群、私聊与联系人卡片，并提供受保护的 send_message / join_chat 写操作。发送默认做精确文本去重；不提供编辑或删除消息。
English: README.en.md

---

Quick Start

1. 安装

git clone https://github.com/runesleo/tg-reader-mcp.git
cd tg-reader-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

2. 一次性登录 + 自检

tg-reader-init

首次运行会自动：

• 使用 Telegram 个人账号登录（非 Bot Token）；按提示输入手机号、验证码，若开启 2FA 再输入密码。
• 创建或复用 ~/.tg-reader-mcp/tg_session.session，并收紧本地文件权限。
• 做一次只读 dialog 拉取自检，确认 session 可用。
• 输出 Claude Desktop 可直接复制的 JSON 和 Claude Code 可直接执行的命令；session 与可执行文件路径都已展开，无需手填绝对路径。

默认 API_ID / API_HASH 与 Telegram Desktop 公开凭据一致。若要使用自己的应用凭据，可先在 my.telegram.org 申请，然后运行：

TG_API_ID=your_id TG_API_HASH=your_hash tg-reader-init

如果直连 Telegram 失败，可用 TG_PROXY_URL（支持 http://、socks5://、socks4://）：

TG_PROXY_URL=http://127.0.0.1:7897 tg-reader-init

初始化时显式设置的 TG_API_ID、TG_API_HASH、TG_PROXY_URL 会自动带进生成的 MCP 配置，避免首次登录与后续运行使用不同参数。

3. 接入 MCP 客户端

• Claude Desktop： 将 tg-reader-init 输出的 tg-reader 条目合并到现有 mcpServers 对象，然后重启 Claude Desktop。
• Claude Code： 直接运行 tg-reader-init 输出的 claude mcp add ... 命令。

---

Tools（与源码一致）

以下名称与 server.py 中 @server.list_tools() 注册项一一对应。

download_media

• 用途： 显式下载某条 Telegram 消息附带的 photo / image / video / document 到本地路径；远端只读。
• 参数： channel（必填）、message_id（必填）、out_dir（可选，默认 ~/.cache/tg-media）。
• 示例：

{ "channel": "durov", "message_id": 12345 }

list_dialogs

• 用途： 列出对话（频道 / 群 / 私聊），支持组合过滤与关键词。
• 参数：
  • filter（可选）：如 unread、unread_dm、unread_channel、channel、group、dm 等组合；否则按对话标题 / username 子串匹配。
  • limit（可选，默认 50）：最多返回条数。
• 示例：

{ "filter": "unread_dm", "limit": 30 }

read_channel

• 用途： 读取指定频道或群的近期文本与媒体消息元数据；每条消息同时返回 from_me、sender_id、sender，媒体消息额外带 media / media_hint。
• 参数：
  • channel（必填）：username（如 durov）或可被 Telethon 解析的标题。
  • limit（可选，默认 20，上限 100）。
  • since（可选）：ISO 8601 时间，仅返回严格晚于该时间的消息。
  • offset_date（可选）：ISO 时间，从该时刻向前翻页（配合返回的 next_offset_date）。
• 示例：

{ "channel": "durov", "limit": 10, "since": "2026-04-20T00:00:00+08:00" }

search_channel

• 用途： 在单个频道/群内按关键词搜索消息。
• 参数：
  • channel（必填）
  • keyword（必填）
  • limit（可选，默认 20）
• 示例：

{ "channel": "runesgangalpha", "keyword": "Polymarket", "limit": 15 }

send_message

• 用途： 向私聊、群或频道发送一条纯文本消息。默认在最近 600 秒内做精确文本去重，避免重复发送；可用 dedupe_window_seconds 调整，最大 24 小时。
• 参数： channel（必填）、text（必填）、reply_to（可选）、dedupe_window_seconds（可选，默认 600）。
• 安全： 这是远端写操作，MCP 客户端应要求显式确认。

{ "channel": "username", "text": "hello", "dedupe_window_seconds": 86400 }

join_chat

• 用途： 通过私有邀请链接或公开 username 加入 Telegram 群/频道；已加入时幂等返回，不重复改变成员状态。