一、用途 mcp-telegram 是一个基于 MCP（Model Context Protocol）的服务器，用于把 AI 助手（如 Claude、ChatGPT、Cursor 等任意 MCP 客户端）连接到 Telegram。与普通 bot 不同，它作为 userbot 运行在你的个人 Telegram 账号下，基于 GramJS，通过 MTProto 协议直接访问 Telegram API（而非功能受限的 Bot API），因此可完整访问你的聊天、联系人和消息历史。
二、主要能力 工具覆盖全面：官方称提供约 182 个工具，是目前功能最完整的 Telegram MCP 服务器之一。 消息与互动：消息收发、表情回应（reactions）、投票（polls）、定时消息、贴纸、媒体、联系人等。 论坛话题（Forum Topics）：列出话题、读取每个话题的消息、向指定话题发送、按话题统计未读数。 贴纸：搜索贴纸包、浏览已安装/最近使用的贴纸、向任意聊天发送贴纸。 账号与个人资料管理：更新资料、设置 emoji 状态、生日、个人频道、头像，管理隐私设置、会话与自动删除计时器。 聊天文件夹：创建、编辑、删除、重新排序文件夹，切换文件夹标签，读取建议文件夹（v1.33.0）。 全局隐私：读取并设置账号级隐私设置（v1.33.0）。 全局搜索：一次性跨所有聊天搜索消息。 实时轮询：通过无状态游标获取更新；由 agent 自行持有 {pts, qts, date} 状态。 内联机器人与按钮：查询内联机器人、发送结果、按下回调按钮。 Stories：读取对端故事、查看故事浏览统计；发布/编辑/删除故事、回应、置顶、隐身模式、归档、举报（v1.30.0）。 讨论组：获取带评论的频道帖子的讨论组信息，列出可参与讨论的群组（v1.30.0）。 已读回执：查看小群组中谁读了某条消息、你的私聊消息何时被读（v1.30.0）。 管理员控制：切换频道签名、反垃圾、论坛模式、预历史；批准加入请求。 统计：频道与超级群组分析（GetBroadcastStats / GetMegagroupStats）。 Boost 与 Business：boost 状态、booster 列表、Telegram Business 聊天链接增删改查、工作时间、位置、问候/离开/介绍消息。 Star 礼物：浏览可用和已保存礼物、保存/转换礼物、管理 Stars 余额与订阅（需通过 MCP_TELEGRAM_ENABLE_STARS=1 opt-in，v1.34.0）。 共享守护进程：一个后台进程通过单个 Telegram 会话服务多个 MCP 客户端（v1.38.0）。 QR 码登录：用 Telegram 应用扫码完成认证。 会话持久化：登录一次，重启后仍保持连接。 可读输出：发送者名称会被解析，而非仅显示数字 ID。 兼容任意 MCP 客户端：Claude Code、Claude Desktop、ChatGPT、Cursor、VS Code、Mastra 等。
三、使用方式 前置要求：Node.js 18 或更高版本；以及来自 my.telegram.org 的 Telegram API 凭据（API_ID 和 API_HASH）。
- 获取 Telegram API 凭据
- 访问 my.telegram.org 并用手机号登录。
- 进入 API development tools。
- 创建一个新应用（名称和平台任意）。
- 复制 App api_id 和 App api_hash。
登录：终端会出现 QR 码。打开手机 Telegram，进入设置 > 设备 > 链接桌面设备，扫描该二维码。会话保存到 ~/.mcp-telegram/session 并自动复用。可通过 TELEGRAM_SESSION_PATH=/path/to/session 自定义会话路径。若账号启用了两步验证（云密码），仅扫码不够，还需通过 TELEGRAM_2FA_PASSWORD 提供密码；该密码仅在本地用于应答 Telegram 的 SRP 挑战，不会被持久化保存。
- 添加到 Claude：完成后可让 Claude 运行 telegram-status 验证。
多账号：使用 TELEGRAM_SESSION_PATH 并行运行多个 Telegram 账号，再分别添加为独立的 MCP 服务器；每个账号有独立会话文件，互不冲突。
多 agent / 并发客户端（共享守护进程）：若一个账号要被多个客户端同时驱动（多个 Claude Code 窗口、并行子 agent 或多个 IDE），常规方式会因 AUTH_KEY_DUPLICATED 互相挤掉。serve 模式可解决：运行单个持久守护进程持有唯一的 Telegram 连接，其他进程通过 PID 锁自动发现守护进程，并经本地 Unix socket 代理工具调用。各 MCP 客户端指向同一安装并使用相同 TELEGRAM_SESSION_PATH（不带 serve 参数），会自动连接守护进程；关闭任一客户端不会断开共享连接。凭据只需守护进程（所有者）提供，客户端命令可省略 TELEGRAM_API_ID / TELEGRAM_API_HASH。
网络受限场景：若 Telegram 被封锁或在容器环境（Docker、K3s）中运行，可使用 SOCKS5 或 MTProxy；若出站 443 端口可用但默认 MTProto 80 端口不可用（部分云厂商对 Telegram DC 网段封禁 80 端口），可通过 WSS（443 端口）连接。
安装选项
- npx（推荐，零安装）：无需克隆或安装，直接使用 npx @overpod/mcp-telegram。
- 预构建二进制（无需运行时）：从 Releases 下载独立单文件二进制，零依赖。登录需交互式终端执行一次（会话持久化在 ~/.mcp-telegram 并自动复用），之后运行 MCP 服务器即可。
与 MCP 客户端配合
- Claude Code（CLI）。
- Claude Desktop：配置文件 macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%\Claude\claude_desktop_config.json；添加 Telegram 服务器后重启。可让 Claude 运行 telegram-login，出现 QR 码（若图片不可见也会保存到 ~/.mcp-telegram/qr-login.png），在 Telegram 中扫描（设置 > 设备 > 链接桌面设备）；再运行 telegram-status 验证。此方式无需终端，登录完全通过 Claude Desktop 完成。
- Claude Desktop（二进制）：同样配置，但改用预构建二进制而非 npx。
- Claude Desktop（Docker）：需先在终端登录，再添加配置并重启，运行 telegram-status 验证。
- Cursor / VS Code：把同样的 JSON 配置加入 MCP 设置（Cursor 设置 > MCP，或 VS Code MCP 配置）。所有工具通过 MCP 自动发现，连接后 AI 客户端会看到带参数和描述的完整列表。可向 AI 助手询问“有哪些 Telegram 工具可用”来获取完整列表。
可选功能：部分工具默认禁用，需通过环境变量 opt-in，可加入 .env 文件或 MCP 客户端配置。
技术栈：TypeScript（ES2022、ESM 模块）、GramJS（telegram）MTProto 客户端、@modelcontextprotocol/sdk（MCP 服务器框架）、Zod（工具参数运行时 schema 校验）、Biome（linter 与格式化）、tsx（无需构建步骤运行 TypeScript）、dotenv（环境变量管理）。
四、适用场景 适合需要在 AI 客户端内直接操作个人 Telegram 账号的场景，例如跨聊天搜索消息、读取与发送消息、管理联系人、处理媒体、查看频道统计、管理 Business 设置、发布或管理 Stories 等，并可作为多客户端共享的单一 Telegram 连接。
五、限制与安全
- 会话同一时间只能被一个进程使用；若出现 AUTH_KEY_DUPLICATED，说明另一进程已在使用同一会话文件，需为每个环境创建独立会话并相应设置 TELEGRAM_SESSION_PATH。
- API 凭据保存在 .env（已 gitignore）；会话保存在 ~/.mcp-telegram/session，权限为 0600（仅所有者可访问），会话目录权限为 0700。
- 不需要手机号——仅用 QR 认证；不向第三方服务发送数据，所有通信经 MTProto 直连 Telegram 服务器；QR 登录码在本地生成，不离开你的机器。
- 这是 userbot（个人账号）而非 bot，需遵守 Telegram 服务条款。
