Telegram MCP Server - 程序化控制Telegram的强大工具

Posted on 十月 11, 2025

Telegram MCP Server - 程序化控制Telegram的强大工具

社区实现 | Stars: 372 | Python | MIT License

概述

Telegram MCP Server 是一个功能完整的 Telegram 集成服务器，基于 Telethon 和 Model Context Protocol (MCP) 构建。它让 AI 助手（如 Claude、Cursor）能够程序化地与 Telegram 账户交互，涵盖聊天管理、消息收发、联系人管理、用户资料操作和搜索发现等全方位功能。

该服务器通过 MCP 协议暴露了数十个 Telegram 工具，使得 AI 能够理解自然语言指令并执行复杂的 Telegram 操作。无论是自动化消息管理、批量群组操作，还是用户数据采集，Telegram MCP Server 都能提供强大的支持。

核心特性

✅ 完整的 Telegram API 支持，基于 Telethon 实现
🛠️ 60+ 工具函数，覆盖所有主要 Telegram 功能
💬 聊天和群组管理（创建、编辑、权限控制等）
📨 消息操作（发送、编辑、删除、转发、置顶等）
👥 联系人管理（添加、删除、屏蔽、搜索等）
👤 用户资料操作（查询、更新、头像管理等）
🔍 搜索和发现（全局搜索、消息搜索、附近聊天等）
🔄 强大的错误处理，支持多重回退策略
🔐 灵活的会话管理，支持文件和字符串会话
🐳 多种部署方式（本地、Docker、Docker Compose）

工具列表

聊天和群组管理（19个工具）

1. get_chats

功能：获取分页的聊天列表

参数：

page (integer, 可选) - 页码，从1开始（默认：1）
page_size (integer, 可选) - 每页聊天数量（默认：20）

返回：聊天ID和标题的格式化字符串

示例：

{
  "page": 1,
  "page_size": 20
}

2. list_chats

功能：列出聊天并支持元数据和过滤

参数：

chat_type (string, 可选) - 聊天类型过滤器
limit (integer, 可选) - 返回结果数量限制

示例：

{
  "chat_type": "group",
  "limit": 50
}

3. get_chat

功能：获取特定聊天的详细信息

参数：

chat_id (integer, 必需) - 聊天ID

示例：

1
2
3

{
  "chat_id": 123456789
}

4. create_group

功能：创建新群组并添加指定用户

参数：

title (string, 必需) - 群组标题
user_ids (array, 必需) - 用户ID列表

示例：

{
  "title": "我的新群组",
  "user_ids": [111111, 222222, 333333]
}

5. create_channel

功能：创建频道或超级群组

参数：

title (string, 必需) - 频道标题
about (string, 可选) - 频道简介
megagroup (boolean, 可选) - 是否为超级群组（默认：false）

示例：

{
  "title": "技术分享频道",
  "about": "分享最新技术动态",
  "megagroup": false
}

6. edit_chat_title

功能：修改聊天/群组/频道的标题

参数：

chat_id (integer, 必需) - 聊天ID
title (string, 必需) - 新标题

7. delete_chat_photo

功能：删除聊天/群组/频道的头像

参数：

chat_id (integer, 必需) - 聊天ID

8. leave_chat

功能：退出群组或频道

参数：

chat_id (integer, 必需) - 聊天ID

9. get_participants

功能：获取聊天的所有参与者

参数：

chat_id (integer, 必需) - 聊天ID

返回：参与者列表，包含用户ID、用户名、姓名等信息

10. get_admins

功能：获取聊天的所有管理员

参数：

chat_id (integer, 必需) - 聊天ID

返回：管理员列表及其权限信息

11. get_banned_users

功能：获取聊天中所有被封禁的用户

参数：

chat_id (integer, 必需) - 聊天ID

12. promote_admin

功能：提升用户为管理员

参数：

chat_id (integer, 必需) - 聊天ID
user_id (integer, 必需) - 用户ID

13. demote_admin

功能：将管理员降级为普通用户

参数：

chat_id (integer, 必需) - 聊天ID
user_id (integer, 必需) - 用户ID

14. ban_user

功能：封禁聊天中的用户

参数：

chat_id (integer, 必需) - 聊天ID
user_id (integer, 必需) - 用户ID

15. unban_user

功能：解除用户封禁

参数：

chat_id (integer, 必需) - 聊天ID
user_id (integer, 必需) - 用户ID

16. get_invite_link

功能：获取群组/频道的邀请链接

参数：

chat_id (integer, 必需) - 聊天ID

返回：邀请链接（支持多重回退方法）

17. export_chat_invite

功能：导出聊天邀请

参数：

chat_id (integer, 必需) - 聊天ID

18. import_chat_invite

功能：通过hash导入聊天邀请

参数：

hash (string, 必需) - 邀请hash

19. join_chat_by_link

功能：通过链接加入聊天

参数：

link (string, 必需) - 邀请链接

示例：

1
2
3

{
  "link": "https://t.me/joinchat/xxxxx"
}

消息操作（14个工具）

1. get_messages

功能：获取分页的消息列表

参数：

chat_id (integer, 必需) - 聊天ID
page (integer, 可选) - 页码（默认：1）
page_size (integer, 可选) - 每页消息数量（默认：20）

示例：

{
  "chat_id": 123456789,
  "page": 1,
  "page_size": 50
}

2. list_messages

功能：列出消息并支持搜索和日期过滤

参数：

chat_id (integer, 必需) - 聊天ID
limit (integer, 可选) - 结果数量限制
search_query (string, 可选) - 搜索查询
from_date (string, 可选) - 起始日期
to_date (string, 可选) - 结束日期

示例：

{
  "chat_id": 123456789,
  "search_query": "重要通知",
  "from_date": "2025-10-01",
  "to_date": "2025-10-14"
}

3. send_message

功能：发送消息到指定聊天

参数：

chat_id (integer, 必需) - 聊天ID
message (string, 必需) - 消息内容

示例：

{
  "chat_id": 123456789,
  "message": "你好，这是一条测试消息"
}

4. reply_to_message

功能：回复特定消息

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 要回复的消息ID
text (string, 必需) - 回复内容

示例：

{
  "chat_id": 123456789,
  "message_id": 12345,
  "text": "感谢您的反馈"
}

5. edit_message

功能：编辑已发送的消息

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 消息ID
new_text (string, 必需) - 新消息内容

6. delete_message

功能：删除消息

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 消息ID

7. forward_message

功能：转发消息到其他聊天

参数：

from_chat_id (integer, 必需) - 源聊天ID
message_id (integer, 必需) - 消息ID
to_chat_id (integer, 必需) - 目标聊天ID

示例：

{
  "from_chat_id": 111111,
  "message_id": 12345,
  "to_chat_id": 222222
}

8. pin_message

功能：置顶消息

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 消息ID

9. unpin_message

功能：取消置顶消息

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 消息ID

10. mark_as_read

功能：标记聊天消息为已读

参数：

chat_id (integer, 必需) - 聊天ID

11. get_message_context

功能：获取消息的上下文（前后消息）

参数：

chat_id (integer, 必需) - 聊天ID
message_id (integer, 必需) - 消息ID
context_size (integer, 可选) - 上下文大小（默认：5）

示例：

{
  "chat_id": 123456789,
  "message_id": 12345,
  "context_size": 10
}

12. get_history

功能：获取聊天历史记录

参数：

chat_id (integer, 必需) - 聊天ID
limit (integer, 可选) - 消息数量限制

13. get_pinned_messages

功能：获取聊天的所有置顶消息

参数：

chat_id (integer, 必需) - 聊天ID

14. search_messages

功能：在聊天中搜索消息

参数：

chat_id (integer, 必需) - 聊天ID
query (string, 必需) - 搜索查询

联系人管理（7个工具）

1. get_contacts

功能：获取所有联系人列表

返回：联系人列表，包含用户ID、用户名、姓名等信息

2. search_contacts

功能：搜索联系人

参数：

query (string, 必需) - 搜索查询

示例：

1
2
3

{
  "query": "张三"
}

3. add_contact

功能：添加新联系人

参数：

phone (string, 必需) - 手机号码
first_name (string, 必需) - 名字
last_name (string, 可选) - 姓氏

示例：

{
  "phone": "+8613800138000",
  "first_name": "张",
  "last_name": "三"
}

4. delete_contact

功能：删除联系人

参数：

user_id (integer, 必需) - 用户ID

5. block_user

功能：屏蔽用户

参数：

user_id (integer, 必需) - 用户ID

6. unblock_user

功能：取消屏蔽用户

参数：

user_id (integer, 必需) - 用户ID

7. get_blocked_users

功能：获取所有已屏蔽用户列表

用户和资料（6个工具）

1. get_user

功能：获取用户的详细信息

参数：

user_id (integer, 必需) - 用户ID

返回：用户详细信息，包括用户名、姓名、头像、简介等

2. get_me

功能：获取当前登录账户的信息

返回：当前用户的完整信息

3. update_profile

功能：更新个人资料

参数：

first_name (string, 可选) - 名字
last_name (string, 可选) - 姓氏
about (string, 可选) - 个人简介

示例：

{
  "first_name": "李",
  "last_name": "四",
  "about": "软件工程师"
}

4. update_username

功能：更新用户名

参数：

username (string, 必需) - 新用户名

5. get_profile_photos

功能：获取用户的所有头像

参数：

user_id (integer, 必需) - 用户ID

6. delete_profile_photos

功能：删除头像

参数：

photo_ids (array, 必需) - 要删除的头像ID列表

搜索和发现（5个工具）

1. search_global

功能：全局搜索用户、群组、频道

参数：

query (string, 必需) - 搜索查询
limit (integer, 可选) - 结果数量限制

示例：

{
  "query": "Python编程",
  "limit": 20
}

2. search_messages

功能：在聊天中搜索消息

参数：

chat_id (integer, 必需) - 聊天ID
query (string, 必需) - 搜索查询

3. get_nearby_chats

功能：获取附近的聊天（基于地理位置）

参数：

latitude (number, 必需) - 纬度
longitude (number, 必需) - 经度

示例：

{
  "latitude": 39.9042,
  "longitude": 116.4074
}

4. resolve_username

功能：通过用户名解析获取实体信息

参数：

username (string, 必需) - 用户名（不包含@）

示例：

1
2
3

{
  "username": "telegram"
}

5. get_common_chats

功能：获取与指定用户的共同群组

参数：

user_id (integer, 必需) - 用户ID

配置方式

环境变量

首先需要在 https://my.telegram.org/apps 获取 Telegram API 凭证：

# Telegram API ID（必需）
TELEGRAM_API_ID=12345678

# Telegram API Hash（必需）
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890

# Telegram 会话字符串（必需）
TELEGRAM_SESSION_STRING=your_generated_session_string

生成会话字符串

# 克隆仓库
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

# 安装依赖
uv sync

# 运行会话生成脚本
python generate_session.py

运行后按照提示输入手机号码和验证码，即可生成会话字符串。

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/telegram-mcp",
        "run",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "12345678",
        "TELEGRAM_API_HASH": "abcdef1234567890abcdef1234567890",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}

Cursor 配置

在 Cursor 设置中添加 MCP 服务器配置，配置方式与 Claude Desktop 类似。

Docker 部署

# 使用 Docker 运行
docker build -t telegram-mcp .
docker run -e TELEGRAM_API_ID="12345678" \
           -e TELEGRAM_API_HASH="abcdef1234567890" \
           -e TELEGRAM_SESSION_STRING="your_session" \
           telegram-mcp

Docker Compose 部署

创建 docker-compose.yml：

version: '3.8'
services:
  telegram-mcp:
    build: .
    environment:
      - TELEGRAM_API_ID=${TELEGRAM_API_ID}
      - TELEGRAM_API_HASH=${TELEGRAM_API_HASH}
      - TELEGRAM_SESSION_STRING=${TELEGRAM_SESSION_STRING}
    restart: unless-stopped

运行：

1	docker-compose up -d

使用场景

1. Telegram 账户自动化

通过自然语言指令让 AI 完成复杂的 Telegram 操作。

示例流程：

用户：”帮我给所有群组管理员发送本周会议通知”
AI 使用 get_chats 获取群组列表
对每个群组使用 get_admins 获取管理员
使用 send_message 发送通知

2. 消息批量管理

自动化处理大量消息，提高效率。

示例流程：

用户：”标记所有未读消息为已读”
AI 使用 get_chats 获取聊天列表
对每个聊天使用 mark_as_read 标记已读

3. 群组监控和管理

自动化群组管理任务，维护群组秩序。

示例流程：

设置规则：新成员加入自动发送欢迎消息
AI 监听新成员事件
使用 send_message 发送欢迎消息
使用 pin_message 置顶群规

4. 数据采集和分析

从 Telegram 采集数据进行分析。

示例流程：

用户：”分析技术群组最近一周的热门话题”
AI 使用 get_messages 获取消息
使用 list_messages 进行过滤
分析消息内容，提取热门关键词

5. 客户服务自动化

自动回复常见问题，提升服务效率。

示例流程：

AI 监听客户消息
识别常见问题类型
使用 reply_to_message 自动回复
复杂问题转发给人工客服

技术架构

核心技术栈

Telegram MCP Server
    |
    +-- Telethon (Telegram MTProto API)
    |
    +-- MCP Python SDK
    |
    +-- 会话管理（文件/字符串）
    |
    +-- 错误处理和日志系统

会话管理

支持两种会话管理方式：

文件会话：会话数据存储在本地文件中
字符串会话：会话数据以字符串形式存储（推荐）

错误处理机制

详细的错误日志：所有错误记录到 mcp_errors.log
多重回退策略：关键功能提供多种实现方法
优雅降级：API 失败时自动尝试备用方案
用户友好的错误消息：清晰的错误提示

账户类型检测

自动检测账户类型（用户账户 vs 机器人账户），并针对性地调用相应的 API。

与其他 MCP 服务器对比

特性	Telegram MCP	Discord MCP	Slack MCP
功能完整性	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
工具数量	60+	30+	40+
消息管理	✅ 完整支持	✅ 支持	✅ 支持
群组管理	✅ 完整支持	✅ 支持	✅ 支持
用户管理	✅ 完整支持	✅ 部分支持	✅ 部分支持
搜索功能	✅ 全局+本地	✅ 本地	✅ 本地
地理位置	✅ 支持	❌ 不支持	❌ 不支持
错误处理	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐

最佳实践

1. 安全配置

# 使用环境变量存储敏感信息
export TELEGRAM_API_ID="your_api_id"
export TELEGRAM_API_HASH="your_api_hash"
export TELEGRAM_SESSION_STRING="your_session"

# 不要在代码中硬编码凭证
# 不要将 .env 文件提交到版本控制

2. 会话字符串生成

1
2
3

# 推荐使用字符串会话而不是文件会话
# 更容易部署和迁移
python generate_session.py

3. 错误处理

1
2
3

# 始终检查操作结果
# MCP Server 会自动记录错误到日志
# 可以查看 mcp_errors.log 了解详情

4. 批量操作优化

对于批量操作（如批量发送消息），建议：

控制速率，避免触发 Telegram 的反垃圾限制
使用分页获取大量数据
合理设置 page_size 和 limit 参数

5. 监控和日志

# 定期检查错误日志
tail -f mcp_errors.log

# 监控服务器状态
# 确保会话保持有效

常见问题

Q: 如何获取 Telegram API 凭证？

访问 https://my.telegram.org/apps，使用手机号登录后创建应用，即可获得 API ID 和 API Hash。

Q: 会话字符串如何生成？

运行项目提供的 generate_session.py 脚本，按照提示输入手机号和验证码，即可生成会话字符串。

Q: 为什么某些文件操作不可用？

由于 MCP 环境对本地文件系统的访问限制，部分需要直接文件路径的工具（如 send_file、download_media 等）已被移除。

Q: GIF 相关功能为什么不可用？

GIF 相关工具由于 Telethon 库或 Telegram API 的可靠性问题暂时被移除。

Q: 如何处理会话过期？

会话字符串理论上是永久有效的，但如果遇到会话过期问题，重新运行 generate_session.py 生成新的会话字符串即可。

Q: 支持多账户吗？

当前实现支持单个 Telegram 账户。如需支持多账户，可以运行多个 MCP Server 实例，每个实例配置不同的会话字符串。

Q: 性能如何？

消息发送: ~10条/秒（受 Telegram API 限制）
消息获取: ~100条/秒
群组操作: 根据操作类型而异
搜索性能: 取决于数据量

Q: 是否支持机器人 API？

该服务器主要针对用户账户设计，但也能自动检测并处理机器人账户的 API 调用。

注意事项

限制和约束

API 限制：Telegram 对 API 调用有速率限制
文件操作：不支持直接文件上传/下载
GIF 操作：暂不支持 GIF 相关功能
会话管理：需要妥善保管会话字符串
账户安全：避免在不可信环境中使用

最佳实践建议

使用专门的 Telegram 账户进行自动化操作
定期备份会话字符串
监控 API 调用频率，避免触发限制
遵守 Telegram 的使用条款和政策
不要用于垃圾信息或滥用行为

评分详情

维度	评分	说明
功能性	4.5/5.0	功能完整，覆盖主要场景
文档质量	4.0/5.0	文档清晰，但可以更详细
社区活跃度	4.2/5.0	社区活跃，issues 响应及时
维护状态	4.5/5.0	持续更新，bug 修复迅速
代码质量	4.3/5.0	代码规范，错误处理完善
综合评分	4.3/5.0	优秀的 Telegram MCP 实现

总结

Telegram MCP Server 是目前功能最完整的 Telegram MCP 实现之一。它基于成熟的 Telethon 库，提供了 60+ 个工具函数，覆盖了聊天管理、消息操作、联系人管理等所有主要 Telegram 功能。

强大的错误处理机制、灵活的会话管理、多种部署方式，使得这个服务器适合各种规模的自动化需求。无论是个人使用还是企业级应用，都能找到合适的使用场景。

推荐指数: ⭐⭐⭐⭐ (4/5)

适合你的情况：

✅ 需要程序化控制 Telegram 账户
✅ 批量消息管理和群组操作
✅ 用户交互自动化
✅ 数据采集和分析
✅ 客户服务自动化

不适合的情况：

❌ 需要大量文件上传/下载操作
❌ 需要 GIF 相关功能
❌ 不能接受 Telegram API 的速率限制
❌ 需要多账户并发操作（需要额外配置）

更新日志

2025-10-14: 完整文档更新，添加所有工具详细说明
2025-10-11: 初始发布，基于 Telethon 和 MCP 实现

更新时间: 2025-10-14
数据来源: GitHub, 质量评分: 4.3/5.0