中文 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 你 。 本 本 本 本 本 本 本 本 本 本 本 本 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 。 英語: README.en.md

お問い合わせ

クイックスタート

##1. 安装

##2. 一次性登記+自治

首次直行会自动:

• Telegram ** ユーザ名**登記 Bot Token, 提示 号 号 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 码 [T2],并收紧本地文件費上限 -一次学習ダイアログ 取消自検索, セッション可用.
• claude デスクトップ 可 直接的 JSON 和 Claude コード 可 直接 行行行行 の ; セッション 可 行 文 件 路径 都 已 展 无 路 开 开 开 开 绝对

[API_ID] / [API_HASH]]] 有料テレグラム デスクトップ 公公 自己 自己 自己 自己 自己 自己

TG_PROXY_URL]( http://]]) socks5://] socks4://]]] :

[T9] [T10]] [T10]] [T11]] [T11]] [T11]] [T11]] [T11]] [T11]] [T11]] [T11]] [T11]] [T11]]] [T11]] [T11] [T11]] [T11] [T11]] [T11]] [T11]] [T11] [T11]] [T11] [T11]] [T11] [T11]]] [T11] [T11]]]

##3. 接入 MCP 客先

• Claude Desktop: 将 tg-reader-init] 出典 [tg-reader]] 条目合結果は有 mcpServers]] 対象物, 正后重本Claudeデスクトップ。 -Claude Code: 直接行 tg-reader-init]] 出典 claude mcp add ... 指示。

お問い合わせ

##ツール与(源流)

[server.py @server.list_tools()] [T18]]

##[download_media

-用途: 風下条条 電報 消息関連性写真/画像/動画/ドキュメント 到着本地路径;終端学習。 -** [channel(必急)T21]([T22])](可選択、[T23])。

• 例:

[[T24]

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 群/频道；已加入时幂等返回，不重复改变成员状态。