Telegram MCP Server：将 Telegram 接入 AI Agent 的桥梁

一款让 AI 助手「看见」并操控 Telegram 的工具

想象一下这样的场景：你在出差途中，收到团队在 Telegram 群里的长串讨论，手边只有手机， 无法快速整理要点。现在，你只需对 Claude 说一句「帮我总结一下昨天群里的关键信息」， AI 就能自动读取 Telegram 聊天记录、筛选重要内容并回复——这不是科幻， 而是 telegram-mcp 已经实现的功能。

图1：Claude 桌面端通过 MCP 协议调用 Telegram 工具

背景：为什么需要 Telegram MCP？

Telegram 是全球最流行的即时通讯工具之一，月活用户超过 9 亿， 尤其在技术社区、开源项目协作和跨境团队中被广泛使用。 然而，主流 AI 助手（Claude、Cursor 等）原生无法直接访问 Telegram， 用户必须在两个界面之间来回切换，效率大打折扣。

telegram-mcp 由开发者 chigwell 和 l1v0n1 创建，旨在解决这一痛点： 通过 Model Context Protocol（MCP）这一标准化协议， 将 Telegram 的核心能力——消息收发、群组管理、联系人、媒体文件等—— 以结构化工具（Tools）的形式暴露给 AI 助手，让 AI 能够「代操作」Telegram， 实现「人类下达指令，AI 执行操作」的自动化工作流。

核心功能：80+ MCP 工具，覆盖 Telegram 全场景

该项目提供了超过 80 个 MCP 工具，按功能分为以下模块：

模块	核心能力
Accounts	多账号管理，路由工具调用到指定账号
Chats & Groups	列出聊天、查看元数据、创建群组/频道、管理管理员、封禁用户、慢速模式、话题、邀请链接等
Messages	发送、定时、编辑、删除、转发、置顶、标记已读、回复、搜索、创建投票、管理表情反应、内联按钮回调等
Contacts	列出、搜索、添加、删除、拉黑、导入导出联系人，查看双向聊天记录
Media	发送/下载文件、语音消息、贴纸、GIF，上传文件
Profile & Privacy	获取/更新个人资料、头像、隐私设置，获取用户信息/头像/在线状态
Folders & Drafts	管理文件夹和草稿

这些工具通过 FastMCP 框架注册为标准 MCP Tools，Claude Desktop、Cline、Cursor 等 MCP 兼容客户端可直接调用，无需任何额外配置。

技术架构：Telethon + FastMCP，简洁而强大

核心技术栈

Python 依赖（pyproject.toml）：

• telethon >= 1.42.0：Telegram 官方 MTProto 客户端库
• mcp[cli] >= 1.8.0：Model Context Protocol SDK
• fastmcp：MCP 服务端实现
• nest_asyncio：修复 Jupyter/Asyncio 兼容问题
• Python >= 3.10

架构分层

整体架构分为三层：

第一层：MCP 客户端 Claude Desktop、Cline、Cursor 等 MCP 兼容客户端，通过 MCP JSON-RPC 协议发送工具调用请求。

第二层：FastMCP Server（telegram-mcp）

• runner.py：应用入口，初始化多账号连接，启动 MCP 服务端
• runtime.py：核心逻辑，加载环境变量、初始化 Telegram 客户端、管理实体会话缓存
• tools/：10 个功能域模块，通过 @mcp.tool() 注册 80+ 工具
• sanitize.py：安全过滤层，对用户生成内容进行 XSS 防护

第三层：Telethon（MTProto） Telethon 库封装了 Telegram 的 MTProto 协议，负责与 Telegram 服务器的加密通信。

安全机制

项目内置两层安全保护：

1. 安装安全：install_guard.py 在启动时检查包是否来自可信来源， 防止 pip install 过程中的供应链攻击（dependency confusion）。

2. 内容过滤：sanitize.py 对用户生成内容（聊天记录、用户名、媒体描述）进行 消毒处理，防止 XSS 和特殊字符注入 MCP 响应。

认证流程

用户无需暴露 Telegram 密码，而是通过 Session String 方式认证：

1. 运行 session_string_generator.py，在终端输入手机号完成 Telegram 登录
2. 生成一串加密字符串，写入 .env 的 TELEGRAM_SESSION_STRING
3. MCP Server 启动时使用该字符串初始化 Telethon 客户端，无需再次交互登录

部署体验：Docker 一键启动，但需提前准备凭证

项目提供了完整的容器化支持：

Dockerfile 基于 python:3.13-alpine，通过 pip install -r requirements.txt 安装依赖， docker-compose.yml 配置了 stdin_open: true 和 tty: true， 这是因为 MCP 服务器通过 stdio（标准输入输出）管道与客户端通信， 容器必须保持交互式终端才能正常工作。

部署步骤

1. 申请 Telegram API 凭证：访问 my.telegram.org → API development tools
2. 生成 Session String：运行 uv run session_string_generator.py
3. 配置 .env 文件（参考 .env.example）
4. 启动：docker-compose up -d
5. 在 Claude Desktop 的 claude_desktop_config.json 中注册 MCP 服务器

部署难点在于第一步申请 API 凭证，其余步骤均有完整文档和自动化脚本支撑。

多账号与代理支持

项目支持同时管理多个 Telegram 账号（多开），通过账号标签（label）区分路由， 适合需要隔离个人号和工作号的场景。此外，通过 TELEGRAM_PROXY_* 系列环境变量 支持 HTTP/SOCKS5 代理，对网络受限环境（如中国大陆）用户非常友好。

局限性与注意事项

问题	说明
无 Web UI	纯 CLI 工具，所有配置通过环境变量管理
Telegram 官方封号风险	频繁 API 调用可能触发风控，建议控制频率
Session String 有效期	长期不活跃可能导致会话失效
隐私风险	AI 读取聊天记录意味着数据会流经 AI 服务商，需确认合规
不支持 Bot	目前仅支持个人账号，不支持 Bot 账号

行业意义：MCP 生态的实用工具标杆

随着 Anthropic 推出 MCP 协议，越来越多的工具开始接入这一标准， 但大多数处于 demo 阶段。telegram-mcp 是少数真正可投产的 MCP 工具：

• 代码质量高：有 pre-commit 检查、CI/CD 流水线（lint + docker build）
• 文档完善：多语言 README、功能分类清晰、troubleshooting 指南完备
• 社区活跃：1200+ Stars，302 Forks，持续更新（最新版本 2.0.1）

它代表了 AI 助手从「对话」向「行动」演进的一个重要方向： AI 不再只是回答问题，而是能够主动操控外部工具执行真实任务。

---

本报告基于 GitHub 仓库 chigwell/telegram-mcp（Stars: 1202+，License: Apache 2.0）生成。