Telegram MCP Server

社区

用Telethon驱动的Telegram MCP服务器，让MCP客户端读取聊天、管理群组、发送/修改消息、媒体、联系人及设置。

分类: 其他
Stars: ★ 1.8k 非常热门
传输方式: stdio（本地进程） · SSE · Streamable HTTP
运行环境: Python 3.10+ · Docker · Node.js
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 今天
工具数: 76

70FMRS · B

此 MCP 服务器功能丰富，提供 80 多个工具，涵盖 Telegram 消息、群组、媒体、联系人和管理功能。它需要用户级会话字符串，因此权限较大，用户应谨慎保管凭证。项目包含安全措施（如只读模式、路径限制、提示注入防护），但仍有风险。安装必须通过克隆或 Git 安装，避免使用 PyPI 上的同名包。

最强项 · 文档质量 17/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

16/20

维护活跃度

14/20

文档质量

17/20

安装易用性

14/20

查看各项评分依据

可靠性 9/20: README 描述了模块化架构（main.py、runtime.py、runner.py、tools/、sanitize.py、tests/）以及异常细致的错误行为（如 telegram_premium_required 结构化结果、未知联系人的引导式返回、代理配置 fail-fast、AuthKeyDuplicatedError 重试）。但本次静态审查拿到的只是 README 自述，没有任何源代码、测试文件或 CI 工作流文件可供执行或核对；README 属于不可信证据，其中的 CI 徽章与 80% 覆盖率门槛无法核实。按静态校准规则，缺少可验证的执行证据时可靠性上限为 12，且证据缺失必须扣分；无法确证工具清单与真实行为一致。因此不给 10 分以上，取 9 分：正常路径看起来可行，但无法依据现有材料复现或诊断失败路径。
安全与权限 16/20: 未发现红线问题：安装示例全部使用占位符（your_api_id_here），无真实密钥；设计文档包含只读工具门控（TELEGRAM_EXPOSED_TOOLS=read-only）、文件工具强制 allowed roots、路径穿越/通配符/空字节拒绝、结构化 JSON 清洗输出与 MCP audience 标注、状态文件仅属主可读（0600）、HTTP 默认绑定 127.0.0.1、DNS 重绑定防护、对 PyPI 同名包的诚实警告及安装守卫、模糊联系人匹配时先确认再发送。凭据走环境变量并有明确的不提交 .env 警告。但该服务器本质上持有完整 Telegram 账户权限，README 也坦承只读模式仅是 MCP 工具面限制而非会话沙箱；且所有防护均无法在真实代码中核实。按‘未验证即扣分’原则取 16 分。
维护活跃度 14/20: 事实性元数据显示仓库未归档、采用 Apache-2.0 许可证、有两位具名维护者（@chigwell、@l1v0n1）、提供含 pre-commit 钩子的贡献指南，README 中还有引用 lint/format 与 Docker 构建工作流的徽章，说明项目处于活跃维护状态。但本次审查未包含提交历史、发布标签、依赖更新记录、issue 响应时效或安全响应渠道等直接证据；34 个未关闭 issue 只能说明存在积压，无法评估响应质量。因此按证据缺失扣分，取 14 分，而非满分。
文档质量 17/20: README 分层且异常详尽：前置要求、会话字符串生成（QR/手机号两种方式）、单/多账户配置、会话池、代理、设备身份、文件路径安全策略、Docker、三种 transport、开发与测试、安全说明、故障排查表，并明确披露限制（富格式需要 Telegram Premium 且每次调用重新检查、PyPI 包名冲突、stdio 与 HTTP 取舍、HTTP 端点无认证等），还给出 Claude/Cursor 的完整客户端配置 JSON 示例。扣分点：逐工具的完整参数参考仅声称存在于服务器内部工具描述中，本次无法核实；除 README 外没有仓库内的其他文档层可查；'80+ 工具''80% 覆盖率门槛'等声明无源码佐证。综合取 17 分。
安装易用性 14/20: 安装路径清晰且有多条可选：git clone + uv sync、uv run session_string_generator.py（--qr/--phone）、cp .env.example 并填写、uv run main.py，随后直接给出 Claude/Cursor 的 stdio 配置 JSON、Docker 运行命令、pip 从 GitHub 安装控制台脚本的方式、mcp-remote 桥接，以及 allowed roots 的 CLI 传参示例，步骤可照抄。按静态校准，未能提供可验证的 CI/测试文件，setup 上限为 15；本次证据中只有 README 描述，且手动生成会话字符串、PyPI 同名包需改用克隆安装等摩擦客观存在，因此取 14 分。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件访问网络修改第三方账户数据

适合谁

开发者希望将 Telegram 集成到 MCP 客户端（如 Claude）
需要管理多个 Telegram 账号的自动化场景
构建自定义 Telegram 机器人或工作流
需要安全文件操作路径限制的场景

不适合谁

需要官方 Bot API 特性的场景（此服务器使用用户客户端）
对终端用户完全托管化的非技术用户
需要多进程同时使用同一会话且无锁管理的场景

所需权限

需要 Telegram API ID 和 API Hash
需要用户的 Telegram 会话字符串（相当于账号访问权限）
可将消息、媒体、联系人和设置发送到任何被允许的聊天
可创建或修改群组、频道和聊天设置
可访问和操作用户的媒体文件和联系人

风险与副作用

会话字符串泄露可能导致账号被入侵
发送消息可能引发隐私或安全问题
提示注入：Telegram 内容可能被恶意构造，需注意防护
来自非官方 PyPI 包名的风险，避免使用 pip 安装 telegram-mcp
多客户端并发可能导致 AuthKeyDuplicatedError

安装接入

准备工作

运行环境：Python 3.10+ · Docker · Node.js

TELEGRAM_API_ID 必填 Telegram API ID，在 my.telegram.org/apps 创建应用后获取，必填。

TELEGRAM_API_HASH 必填密钥 Telegram API 哈希，与 API ID 一起在 my.telegram.org/apps 获取，属于敏感凭据。

TELEGRAM_SESSION_STRING 必填密钥通过仓库中的 session_string_generator.py 生成的已授权会话字符串，等同于账号访问权限，必须保密。

TELEGRAM_SESSION_STRING_WORK 可选密钥可选；多账号模式下 work 账号的会话字符串。

TELEGRAM_SESSION_STRING_PERSONAL 可选密钥可选；多账号模式下 personal 账号的会话字符串。

TELEGRAM_SESSION_STRINGS 可选密钥可选；同一账号多个会话字符串组成会话池，供多个客户端并发使用。

TELEGRAM_PROXY_PASSWORD 可选密钥可选；代理认证密码，属于敏感凭据。

TELEGRAM_PROXY_SECRET 可选密钥可选；MTProxy 类型代理所需的密钥，属于敏感凭据。

其他可选配置项（20 个）

TELEGRAM_EXPOSED_TOOLS 可选可选；设为 read-only 只暴露只读工具，read-only+工具名可附加指定写工具。

TELEGRAM_CONTACT_FUZZY 可选可选；设为 0 关闭联系人别名相似拼写的建议匹配。

TELEGRAM_ALIASES_FILE 可选可选；覆盖联系人别名存储文件的路径。

TELEGRAM_EVENT_FEED 可选可选；设为 1 自动启用传入消息事件订阅流（回调模式）。

TELEGRAM_EVENT_FEED_FILE 可选可选；覆盖传入事件订阅流 JSONL 文件的路径。

TELEGRAM_SESSION_NAME 可选可选；备用会话标识（文件会话名）。

TELEGRAM_DEVICE_MODEL 可选可选；在 Telegram 设置的设备列表中显示的设备型号名。

TELEGRAM_SYSTEM_VERSION 可选可选；显示在设备列表中的系统版本。

TELEGRAM_APP_VERSION 可选可选；显示在设备列表中的应用版本。

TELEGRAM_PROXY_TYPE 可选可选；代理类型，支持 socks5、socks4、http、mtproxy。

TELEGRAM_PROXY_HOST 可选可选；代理服务器主机地址。

TELEGRAM_PROXY_PORT 可选可选；代理服务器端口。

TELEGRAM_PROXY_USERNAME 可选可选；代理认证用户名。

TELEGRAM_PROXY_RDNS 可选可选；是否使用远程 DNS 解析。

MCP_TRANSPORT 可选可选；MCP 传输方式，取值 stdio（默认）、http 或 sse。

MCP_HOST 可选可选；HTTP/SSE 传输的绑定地址，默认 127.0.0.1。

MCP_PORT 可选可选；HTTP/SSE 传输的端口，默认 8765。

MCP_ALLOWED_HOSTS 可选可选；允许的 Host 头列表，用于启用 DNS 重绑定保护。

MCP_ALLOWED_ORIGINS 可选可选；允许的 Origin 列表。

TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK 可选可选；设为 1 时在客户端 Roots 为空或失败时回退使用服务器 CLI 配置的根目录。

克隆仓库并安装依赖：git clone https://github.com/chigwell/telegram-mcp.git && cd telegram-mcp && uv sync。
生成会话字符串：uv run session_string_generator.py --qr（推荐）或 --phone。
复制 .env.example 为 .env 并填写 TELEGRAM_API_ID、TELEGRAM_API_HASH 和 TELEGRAM_SESSION_STRING。
运行服务器：uv run main.py，或配置 MCP 客户端使用 uv --directory /path/to/telegram-mcp run main.py，并传入环境变量。
可选：设置 TELEGRAM_EXPOSED_TOOLS=read-only 以仅暴露只读工具。

claude_desktop_config.json

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add telegram-mcp -e TELEGRAM_API_ID=your_api_id_here -e TELEGRAM_API_HASH=your_api_hash_here -e TELEGRAM_SESSION_STRING=your_session_string_here -- uv --directory /full/path/to/telegram-mcp run main.py

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在 MCP 客户端配置好服务器后重启，工具列表中应出现 list_accounts 和 get_me 等工具；调用 get_me，若返回当前 Telegram 账号信息即说明连接成功。

常见排障

无会话：设置 TELEGRAM_SESSION_STRING 或运行 session_string_generator.py
会话未授权：重新生成会话字符串
API 凭据无效：检查 my.telegram.org 的 API ID 和 Hash
数据库锁定：使用字符串会话或避免多个进程使用同一文件
文件工具禁用：配置允许根路径或 MCP Roots
路径被拒绝：确保路径在允许根内且无通配符
认证错误：重新生成会话字符串
查看 mcp_errors.log 和客户端日志获取详细信息

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出我所有的 Telegram 账号，并显示每个账号的未读消息
搜索我聊天记录中提到项目截止日期的消息，并总结讨论内容
给 @example 发送一条消息，说明明天的会议改到下午三点
为我的工作群组创建一个新的邀请链接，并把某位成员设为管理员

工具能力 76

list_accounts 只读

列出已配置的 Telegram 账号。

get_me 只读

获取当前账号的信息。

update_profile 写入

set_profile_photo 写入

delete_profile_photo 破坏性

list_chats 只读

列出聊天。

get_chat 只读

获取聊天元数据。

create_group 写入

创建群组。

展开其余 68 个工具

create_channel 写入

创建频道。

join_chat 写入

加入聊天。

leave_chat 写入

离开聊天。

invite_users 写入

邀请用户。

get_participants 只读

获取参与者列表。

promote_admin 写入

提升为管理员。

demote_admin 写入

降级管理员。

ban_user 写入

封禁用户。

unban_user 写入

解除封禁。

set_default_permissions 写入

设置默认权限。

set_slow_mode 写入

设置慢速模式。

manage_topics 写入

管理话题。

create_invite_link 写入

创建邀请链接。

revoke_invite_link 写入

撤销邀请链接。

get_common_chats 只读

获取共同聊天。

get_read_receipts 只读

获取已读回执。

get_message_link 只读

获取消息链接。

send_message 写入

发送消息，支持 Markdown/HTML 格式化。

reply_to_message 写入

edit_message 写入

编辑已发送的消息。

delete_message 破坏性

删除一条消息。

forward_message 写入

转发消息到其他聊天。

pin_message 写入

固定一条消息。

unpin_message 写入

取消固定消息。

mark_read 写入

将聊天标记为已读。

search_messages 只读

在聊天中搜索消息。

get_message_context 只读

create_poll 写入

创建投票。

manage_reactions 写入

管理消息回应。

get_inline_buttons 只读

press_inline_button 写入

set_contact_alias 写入

设置联系人别名。

list_contact_aliases 只读

列出联系人别名。

delete_contact_alias 破坏性

删除联系人别名。

list_contacts 只读

列出联系人。

search_contacts 只读

add_contact 写入

添加联系人。

delete_contact 破坏性

block_contact 写入

屏蔽联系人。

unblock_contact 写入

解除屏蔽联系人。

import_contacts 写入

export_contacts 只读

get_direct_chats 只读

recent_contact_interactions 只读

send_file 写入

发送文件。

download_media 写入

下载媒体。

upload_file 写入

上传文件。

send_voice 写入

发送语音消息。

send_sticker 写入

发送贴纸。

send_gif 写入

发送 GIF。

get_message_media 只读

get_user_info 只读

get_user_photos 只读

get_user_status 只读

manage_bot_commands 写入

list_folders 只读

create_folder 写入

update_folder 写入

reorder_folders 写入

delete_folder 破坏性

save_draft 写入

list_drafts 只读

clear_drafts 破坏性

wait_for_new_message 只读

等待新消息（带防抖）。

wait_for_settled_message 只读

等待消息稳定后返回。

enable_incoming_feed 写入

启用传入事件源（回调模式）。

disable_incoming_feed 写入

禁用传入事件源。

incoming_feed_status 只读

查询事件源状态。

使用场景

让 AI 助手读取和分析 Telegram 聊天历史

通过自然语言命令发送消息、转发、编辑消息

自动化群组管理，如添加/移除成员、设置权限

下载媒体文件或上传文件到聊天

管理联系人列表和自定义别名

支持客户端

Claude Desktop

Cursor

Claude Code

Codex

依据项目文档列出，未经本站实测。

详细介绍

telegram-mcp 是一个基于 Telethon 的 Model Context Protocol (MCP) 服务器，为 Claude、Cursor 等 MCP 兼容客户端提供完整的 Telegram 集成。它通过 80 多个工具暴露 Telegram 账号、聊天、消息、联系人、媒体、文件夹和管理员操作。支持多种传输方式（stdio、HTTP、SSE），并提供多账号支持、代理支持、联系人别名记忆、只读模式、文件路径安全防护、Docker 部署以及针对提示注入的防护。