适合谁
- 开发者希望将 Telegram 集成到 MCP 客户端（如 Claude）
- 需要管理多个 Telegram 账号的自动化场景
- 构建自定义 Telegram 机器人或工作流
- 需要安全文件操作路径限制的场景
T
70FMRS · B
此 MCP 服务器功能丰富，提供 80 多个工具，涵盖 Telegram 消息、群组、媒体、联系人和管理功能。它需要用户级会话字符串，因此权限较大，用户应谨慎保管凭证。项目包含安全措施（如只读模式、路径限制、提示注入防护），但仍有风险。安装必须通过克隆或 Git 安装，避免使用 PyPI 上的同名包。
telegram-mcp 是一个基于 Telethon 的 Model Context Protocol (MCP) 服务器，为 Claude、Cursor 等 MCP 兼容客户端提供完整的 Telegram 集成。它通过 80 多个工具暴露 Telegram 账号、聊天、消息、联系人、媒体、文件夹和管理员操作。支持多种传输方式（stdio、HTTP、SSE），并提供多账号支持、代理支持、联系人别名记忆、只读模式、文件路径安全防护、Docker 部署以及针对提示注入的防护。
工具能力
list_accounts
列出已配置的 Telegram 账号。
get_me
获取当前账号的信息。
update_profile
set_profile_photo
delete_profile_photo
list_chats
列出聊天。
get_chat
获取聊天元数据。
create_group
创建群组。
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
查询事件源状态。
安装接入
- 克隆仓库并安装依赖：
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"
}
}
}
}
选型与风险
不适合谁
- 需要官方 Bot API 特性的场景（此服务器使用用户客户端）
- 对终端用户完全托管化的非技术用户
- 需要多进程同时使用同一会话且无锁管理的场景
所需权限
- 需要 Telegram API ID 和 API Hash
- 需要用户的 Telegram 会话字符串（相当于账号访问权限）
- 可将消息、媒体、联系人和设置发送到任何被允许的聊天
- 可创建或修改群组、频道和聊天设置
- 可访问和操作用户的媒体文件和联系人
风险与副作用
- 会话字符串泄露可能导致账号被入侵
- 发送消息可能引发隐私或安全问题
- 提示注入：Telegram 内容可能被恶意构造，需注意防护
- 来自非官方 PyPI 包名的风险，避免使用 pip 安装 telegram-mcp
- 多客户端并发可能导致 AuthKeyDuplicatedError
常见排障
- 无会话：设置 TELEGRAM_SESSION_STRING 或运行 session_string_generator.py
- 会话未授权：重新生成会话字符串
- API 凭据无效：检查 my.telegram.org 的 API ID 和 Hash
- 数据库锁定：使用字符串会话或避免多个进程使用同一文件
- 文件工具禁用：配置允许根路径或 MCP Roots
- 路径被拒绝：确保路径在允许根内且无通配符
- 认证错误：重新生成会话字符串
- 查看 mcp_errors.log 和客户端日志获取详细信息
使用场景
让 AI 助手读取和分析 Telegram 聊天历史
通过自然语言命令发送消息、转发、编辑消息
自动化群组管理，如添加/移除成员、设置权限
下载媒体文件或上传文件到聊天
管理联系人列表和自定义别名
支持客户端
Claude Desktop完整支持
Cursor完整支持
Claude Code完整支持
Codex完整支持