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 服务器的加密通信。

安全机制

项目内置两层安全保护：

安装安全：install_guard.py 在启动时检查包是否来自可信来源，防止 pip install 过程中的供应链攻击（dependency confusion）。
内容过滤：sanitize.py 对用户生成内容（聊天记录、用户名、媒体描述）进行消毒处理，防止 XSS 和特殊字符注入 MCP 响应。

认证流程

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

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

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

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

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

部署步骤

申请 Telegram API 凭证：访问 my.telegram.org → API development tools
生成 Session String：运行 uv run session_string_generator.py
配置 .env 文件（参考 .env.example）
启动：docker-compose up -d
在 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）生成。

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

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

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

背景：为什么需要 Telegram MCP？

核心功能：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 服务器的加密通信。

安全机制

项目内置两层安全保护：

安装安全：install_guard.py 在启动时检查包是否来自可信来源，防止 pip install 过程中的供应链攻击（dependency confusion）。
内容过滤：sanitize.py 对用户生成内容（聊天记录、用户名、媒体描述）进行消毒处理，防止 XSS 和特殊字符注入 MCP 响应。

认证流程

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

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

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

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

部署步骤

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

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

多账号与代理支持

局限性与注意事项

问题	说明
无 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）生成。