Telegram MCP Complete

Telegram MCP Complete

Enables AI-powered multi-account Telegram management with over 123 tools for messaging, group/channel operations, scheduling, and AI message polishing.

Category
访问服务器

README

<div align="center">

<!-- Logo --> <img src="https://img.icons8.com/color/96/000000/telegram-app.png" alt="Telegram MCP" width="80" height="80">

<!-- Main Title --> <h1 align="center">Telegram MCP Complete</h1>

<!-- Tagline --> <p align="center"> <strong>AI 驱动的 Telegram 多账号管理神器</strong> <br> <em>123+ MCP 工具 | 一键群发 | 定时任务 | AI 智能润色 | Web 后台</em> </p>

<!-- Badges Row 1: Status & Version --> <p align="center"> <a href="https://github.com/you922/telegram-mcp/stargazers"> <img alt="Stars" src="https://img.shields.io/github/stars/you922/telegram-mcp?style=for-the-badge&logo=github&colorB=f5c518&labelColor=333"> </a> <a href="https://github.com/you922/telegram-mcp/network/members"> <img alt="Forks" src="https://img.shields.io/github/forks/you922/telegram-mcp?style=for-the-badge&logo=github&color=2f9ed3&labelColor=333"> </a> <a href="https://github.com/you922/telegram-mcp/issues"> <img alt="Issues" src="https://img.shields.io/github/issues/you922/telegram-mcp?style=for-the-badge&logo=github&color=e5554e&labelColor=333"> </a> <a href="https://github.com/you922/telegram-mcp/blob/main/LICENSE"> <img alt="License" src="https://img.shields.io/github/license/you922/telegram-mcp?style=for-the-badge&logo=github&color=3da639&labelColor=333"> </a> </p>

<!-- Badges Row 2: Tech Stack --> <p align="center"> <img alt="Python" src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white"> <img alt="MCP" src="https://img.shields.io/badge/MCP-Protocol-FF6B6B?style=flat-square"> <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-0.104+-009688?style=flat-square&logo=fastapi&logoColor=white"> <img alt="Telethon" src="https://img.shields.io/badge/Telethon-1.34+-E53935?style=flat-square"> <img alt="Vue.js" src="https://img.shields.io/badge/Vue.js-3.x-4FC08D?style=flat-square&logo=vue.js&logoColor=white"> <img alt="Docker" src="https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white"> </p>

<!-- Navigation --> <p align="center"> <a href="#-核心特性"><strong>特性</strong></a> • <a href="#-快速开始"><strong>快速开始</strong></a> • <a href="#-mcp-工具列表"><strong>工具</strong></a> • <a href="#-界面预览"><strong>截图</strong></a> • <a href="#-常见问题"><strong>FAQ</strong></a> • <a href="#-贡献指南"><strong>贡献</strong></a> </p>

</div>

💡 灵感来源

本项目灵感来自 KT智能拓客 - 官网 | 客服

🌟 核心特性

🚀 五大核心优势

特性 说明
🤖 123+ MCP 工具 覆盖 Telegram 所有常用操作，AI 像真人一样操作
📱 双登录模式 二维码扫描 + 手机号验证码（支持 177 个国家/地区）
🌐 Web Dashboard 可视化管理界面，无需编程即可操作
🔄 自动化 定时任务、消息模板、批量发送、AI 润色
🔐 安全可靠 本地存储、2FA 支持、代理保护、风险监控

📊 功能一览

┌─────────────────────────────────────────────────────────────┐
│                    Telegram MCP Complete                     │
├─────────────────────────────────────────────────────────────┤
│  🤖 MCP 服务器                                                │
│  ├─ 123 个 AI 工具                                            │
│  ├─ 消息发送/接收/转发/编辑/删除                               │
│  ├─ 群组/频道/聊天管理                                        │
│  ├─ 联系人/用户/封禁/拉黑                                      │
│  └─ 文件/图片/视频/语音/贴纸                                   │
│                                                              │
│  🌐 Web Dashboard                                            │
│  ├─ 多账号管理（状态实时监控）                                  │
│  ├─ 代理配置（全局 + 独立）                                    │
│  ├─ 定时任务（Cron + 精确时间）                                │
│  ├─ 消息模板（变量替换）                                       │
│  ├─ 健康监控（风险识别）                                       │
│  └─ 操作日志（完整记录）                                       │
│                                                              │
│  🎯 高级功能                                                   │
│  ├─ AI 智能润色（情感优化、内容扩写）                            │
│  ├─ 批量发送（好友 + 陌生人用户名）                              │
│  ├─ 自动去重（用户名验证、重复过滤）                              │
│  ├─ 发送间隔（500ms - 50s 可调）                                │
│  └─ 定时触发（仅一次/每天/每周/工作日）                          │
└─────────────────────────────────────────────────────────────┘

⚡ 快速开始

方式一：扫码登录（推荐）

# 1. 克隆项目
git clone https://github.com/you922/telegram-mcp.git
cd telegram-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动 Dashboard
python dashboard.py

# 4. 打开浏览器访问
# http://localhost:8080/static/dashboard.html

# 5. 点击"添加账号" → "扫码登录"
#    用手机 Telegram 扫描二维码即可

方式二：手机号登录

┌─────────────────────────────────────┐
│  添加账号                            │
├─────────────────────────────────────┤
│  选择国家/地区                       │
│  ┌─────────────────────────────┐    │
│  │ 🔍 搜索...                  │    │
│  │ 🇨🇳 中国 +86                │    │
│  │ 🇺🇸 美国 +1                 │    │
│  │ 🇬🇧 英国 +44                │    │
│  │ 🇯🇵 日本 +81                │    │
│  │ 🇰🇷 韩国 +82                │    │
│  │ ... 支持 177 个国家/地区     │    │
│  └─────────────────────────────┘    │
│                                      │
│  手机号: [_______________]           │
│                                      │
│  [获取验证码]                        │
└─────────────────────────────────────┘

配置 Claude Code

编辑 Claude Code 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "python",
      "args": ["/path/to/telegram-mcp/main.py"]
    }
  }
}

重启 Claude Code 后即可使用：

你: 查看我的 Telegram 聊天列表
AI: [调用 get_dialogs 工具]

你: 给 @username 发消息说你好
AI: [调用 send_message 工具]

你: 帮我创建一个叫"测试群"的群组
AI: [调用 create_group 工具]

🎯 AI 智能润色示例

原始消息 AI 润色后 效果
"早上好" "☀️ 早上好！愿美好的一天从现在开始~" 添加表情符号和温暖语调
"买我的产品" "🤝 您好！我们的产品有这些优势...需要了解一下吗？" 专业且有礼貌
"谢谢关注" "🙏 感谢您的关注和支持！如有需要随时联系~" 热情且亲切

支持的 AI 操作：

  • polish_message - 消息润色
  • expand_message - 内容扩写
  • get_pending_ai_tasks - 获取待润色任务
  • execute_ai_task - 执行润色后发送

📅 定时任务功能

重复模式

模式 说明 适用场景
仅一次 指定时间执行一次后不再执行 一次性通知、提醒
每天 每 24 小时执行一次 每日问候、日报
每周 每 7 天执行一次 周报、周总结
工作日 周一至周五执行，周末不执行 工作日通知、业务消息

发送模式

模式 说明
直接发送 到达时间后自动发送原始消息
AI 润色 到达时间后等待 AI 润色后发送

发送目标

┌─────────────────────────────────────┐
│  选择发送目标                        │
├─────────────────────────────────────┤
│  账号: account_001 ▼                │
│                                      │
│  👥 好友 (125)                       │
│  ┌─────────────────────────────┐    │
│  │ ☑️ 张三                     │    │
│  │ ☑️ 李四                     │    │
│  │ ☑️ 王五                     │    │
│  │ [全选] [反选]               │    │
│  └─────────────────────────────┘    │
│                                      │
│  🌍 陌生人 (用户名)                  │
│  ┌─────────────────────────────┐    │
│  │ @user1, @user2, @user3...   │    │
│  │ 最多支持 5000 个用户名       │    │
│  └─────────────────────────────┘    │
│                                      │
│  ⚙️ 发送设置                         │
│  ├─ 间隔: 2000 毫秒 (500ms-50s)     │
│  └─ 自动去重: ☑️ 启用                │
└─────────────────────────────────────┘

🛠️ MCP 工具列表

<details> <summary><strong>💬 聊天管理 (6 个工具)</strong></summary>

工具 描述
get_chats 获取聊天列表（分页支持）
search_chat 搜索公开群组/频道
get_chat_info 获取聊天详情
join_channel 加入公开频道
leave_chat 离开聊天
get_dialogs 获取对话列表

</details>

<details> <summary><strong>📝 消息操作 (29 个工具)</strong></summary>

工具 描述
send_message 发送文本消息
reply_message 回复消息
edit_message 编辑消息
delete_messages 删除消息
forward_messages 转发消息
pin_message 置顶消息
unpin_message 取消置顶
mark_read 标记已读
search_messages 搜索消息
send_photo 发送图片
send_video 发送视频
send_file 发送文件
send_voice 发送语音
send_audio 发送音频
send_contact 发送联系人
send_location 发送位置
send_poll 创建投票
send_reaction 发送表情反应
get_messages 获取消息
download_media 下载媒体文件
... 更多工具

</details>

<details> <summary><strong>👥 用户/联系人 (12 个工具)</strong></summary>

工具 描述
get_me 获取我的信息
get_user_info 获取用户详情
get_user_status 获取用户在线状态
get_contacts 获取联系人列表
search_contacts 搜索联系人
add_contact 添加联系人
delete_contact 删除联系人
block_user 拉黑用户
unblock_user 解除拉黑
... 更多工具

</details>

<details> <summary><strong>👥 群组/频道 (29 个工具)</strong></summary>

工具 描述
create_group 创建群组
create_supergroup 创建超级群组
create_channel 创建频道
get_members 获取群组成员
get_admins 获取管理员列表
invite_to_chat 邀请进群
kick_from_chat 踢出群组
promote_admin 提升管理员
demote_admin 降级管理员
ban_user 封禁用户
unban_user 解除封禁
set_group_photo 设置群头像
edit_group_title 编辑群名称
set_group_permissions 设置群权限
get_invite_link 获取邀请链接
... 更多工具

</details>

<details> <summary><strong>📅 定时任务 (7 个工具)</strong></summary>

工具 描述
create_schedule 创建定时任务
list_schedules 查看所有任务
delete_schedule 删除任务
toggle_schedule 启用/禁用任务
get_pending_ai_tasks 获取待 AI 润色任务
execute_ai_task 执行润色后发送
schedule_message 定时发送消息

</details>

<details> <summary><strong>📁 文件/媒体 (3 个工具)</strong></summary>

工具 描述
send_file 发送文件
download_media 下载媒体
get_file_info 获取文件信息

</details>

工具总数：123 个

🖼️ 界面预览

Dashboard 主界面

┌──────────────────────────────────────────────────────────────────┐
│  Telegram MCP Dashboard                              🔔  ⚙️     │
├──────────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  📊 统计概览                                               │  │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐   │  │
│  │  │账号  │ │在线  │ │代理  │ │模板  │ │任务  │ │今日  │   │  │
│  │  │  3   │ │  2   │ │  2   │ │  5   │ │  1   │ │ 156  │   │  │
│  │  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘   │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  👥 账号管理              [+ 添加账号]                      │  │
│  │  ┌──────────────────────────────────────────────────────┐ │  │
│  │  │ account_001         🟢 在线    @ktyou211            │ │  │
│  │  │ account_002         🔴 离线    @test_account         │ │  │
│  │  │ account_003         ⚠️ 风险    @spam_account         │ │  │
│  │  └──────────────────────────────────────────────────────┘ │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  🌐 代理设置                                              │  │
│  │  ┌──────────────────────────────────────────────────────┐ │  │
│  │  │ proxy_1 (SOCKS5)        ✅ 215ms    [测试] [删除]     │ │  │
│  │  │ proxy_2 (SOCKS5)        ✅ 856ms    [测试] [删除]     │ │  │
│  │  └──────────────────────────────────────────────────────┘ │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

定时任务管理

┌──────────────────────────────────────────────────────────────────┐
│  📅 定时计划                                   [+ 添加计划]       │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  每日早安                                                  │  │
│  │  每天 09:00  •  启用中  •  上次: 今天 09:00               │  │
│  │  发送给: 5 个好友 + 12 个用户名                            │  │
│  │  消息: ☀️ 早上好！愿美好的一天从现在开始~                   │  │
│  │  [禁用] [删除]                                             │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  产品推广 (AI润色)                                          │  │
│  │  工作日 14:00  •  待执行  •  下次: 明天 14:00              │  │
│  │  发送给: 全部好友 (125人)                                  │  │
│  │  消息: [等待AI润色]                                        │  │
│  │  [禁用] [删除]                                             │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

❓ 常见问题

<details> <summary><strong>Q: 支持哪些登录方式？</strong></summary>

A: 支持两种登录方式：

  1. 二维码登录 - 用手机 Telegram 扫描二维码即可
  2. 手机号登录 - 选择国家/地区（177 个），输入手机号，获取验证码登录

</details>

<details> <summary><strong>Q: Session 安全吗？</strong></summary>

A: 非常安全。Session 仅保存在本地 accounts/config.json 文件中：

  • 不会上传到任何服务器
  • 支持 2FA 两步验证
  • 可通过 Dashboard 管理和删除
  • 不会提交到 GitHub（已在 .gitignore 中）

</details>

<details> <summary><strong>Q: 如何使用代理？</strong></summary>

A: 支持两种代理配置方式：

  1. 全局代理 - 所有账号使用同一个代理
  2. 独立代理 - 为特定账号分配独立代理

支持的协议：HTTP、HTTPS、SOCKS5、SOCKS4

</details>

<details> <summary><strong>Q: 定时任务怎么使用？</strong></summary>

A: 在 Dashboard 中：

  1. 点击"定时计划" → "添加计划"
  2. 输入消息内容或选择已有模板
  3. 设置执行时间（年/月/日/时/分/秒）
  4. 选择重复模式（仅一次/每天/每周/工作日）
  5. 选择发送目标（好友 + 陌生人用户名）
  6. 设置发送间隔和自动去重
  7. 点击"创建计划"

</details>

<details> <summary><strong>Q: AI 润色功能怎么用？</strong></summary>

A: AI 润色通过 MCP 工具实现：

  1. 创建定时任务时选择"AI 执行"模式
  2. 到达执行时间后，任务进入"待润色"队列
  3. AI 通过 get_pending_ai_tasks 获取任务
  4. AI 使用 polish_message 或 expand_message 润色消息
  5. AI 通过 execute_ai_task 发送润色后的消息

</details>

<details> <summary><strong>Q: 可以批量发送吗？</strong></summary>

A: 可以！支持：

  • 选择多个好友（支持全选/反选）
  • 输入陌生人用户名（最多 5000 个）
  • 可同时发送给好友 + 陌生人
  • 自动去重和用户名验证
  • 可设置发送间隔（500ms - 50s）

</details>

<details> <summary><strong>Q: 支持 Docker 部署吗？</strong></summary>

A: 支持！使用 Docker Compose 一键部署：

docker-compose up -d

访问 http://localhost:8080

</details>

📁 项目结构

telegram-mcp/
├── main.py                  # MCP 服务器主入口
├── dashboard.py             # Web 管理后台
├── account_manager.py       # 账号管理
├── proxy_manager.py         # 代理管理
├── scheduler.py             # 定时任务调度器
├── template_manager.py      # 消息模板管理
├── health_monitor.py        # 健康监控
├── log_manager.py           # 日志管理
├── stats_tracker.py         # 统计追踪
├── session_manager.py       # Session 管理
├── web_login.py             # Web 登录
├── static/
│   └── dashboard.html       # 前端页面
├── accounts/                # 数据存储（.gitignore 保护）
│   ├── config.json          # 账号配置
│   ├── proxies.json         # 代理配置
│   ├── templates.json       # 消息模板
│   ├── schedules.json       # 定时任务
│   ├── logs.json            # 操作日志
│   ├── health.json          # 健康数据
│   └── stats.json           # 统计数据
├── requirements.txt         # Python 依赖
├── Dockerfile               # Docker 配置
├── docker-compose.yml       # Docker Compose
├── .env.example             # 环境变量示例
├── .gitignore               # Git 忽略配置
└── LICENSE                  # MIT 许可证

🚀 部署方式

Docker Compose（推荐）

git clone https://github.com/you922/telegram-mcp.git
cd telegram-mcp
docker-compose up -d

手动部署

git clone https://github.com/you922/telegram-mcp.git
cd telegram-mcp
pip install -r requirements.txt
python dashboard.py

服务器部署

# 后台运行
nohup python dashboard.py > dashboard.log 2>&1 &

# 或使用 systemd
sudo cp telegram-mcp.service /etc/systemd/system/
sudo systemctl start telegram-mcp
sudo systemctl enable telegram-mcp

🤝 贡献指南

我们欢迎所有形式的贡献！

如何贡献

  1. 🍴 Fork 本仓库
  2. 🌟 创建你的特性分支 (git checkout -b feature/AmazingFeature)
  3. 💾 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 📤 推送到分支 (git push origin feature/AmazingFeature)
  5. 🔀 开启 Pull Request

开发环境

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

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行
python dashboard.py

📜 许可证

本项目采用 MIT License 开源协议。

MIT License

Copyright (c) 2026 Telegram MCP Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

👥 贡献者

感谢所有为本项目做出贡献的人！

<!-- Contributors -->

🙏 致谢

感谢以下开源项目：

🔗 相关链接

<div align="center">

如果这个项目对你有帮助，请给一个 ⭐️ Star!

⭐ Star • 🍴 Fork • 🐛 报告问题 • 💬 讨论

灵感来源: KT智能拓客 | @ktfy8888

🔝 返回顶部

Made with ❤️ by you922

</div>

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选