Telegram MCP Complete
by you922
README.md
<!--
╔══════════════════════════════════════════════════════════════════════╗
║ DreamSeed 种梦计划 — AI创造者大赛 官方 README 模板 ║
║ ║
║ 使用说明： ║
║ 1. 将本模板放在参赛仓库根目录 README.md 的顶部 ║
║ 2. 头图使用 DreamField 官方公开活动图片地址 ║
║ 3. 请保留 DREAMFIELD_README_HEADER_START / END 标识 ║
║ 4. 分割线以下供创作者自由编写项目内容 ║
╚══════════════════════════════════════════════════════════════════════╝
-->
<!-- DREAMFIELD_README_HEADER_START -->
<p align="center">
<a href="https://www.dreamfield.top">
<img src="https://www.dreamfield.top/dream-field/contest-readme/assets/dreamseed-readme-banner.png" alt="DreamSeed 种梦计划参赛作品" width="100%" />
</a>
</p>
<!-- DREAMFIELD_README_HEADER_END -->
---
<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智能拓客** - [官网](https://ktfy8888.com) | [客服](https://t.me/ktfy8888)
---
## 🌟 核心特性
### 🚀 五大核心优势
| 特性 | 说明 |
|:----:|------|
| **🤖 123+ MCP 工具** | 覆盖 Telegram 所有常用操作，AI 像真人一样操作 |
| **📱 双登录模式** | 二维码扫描 + 手机号验证码（支持 177 个国家/地区） |
| **🌐 Web Dashboard** | 可视化管理界面，无需编程即可操作 |
| **🔄 自动化** | 定时任务、消息模板、批量发送、AI 润色 |
| **🔐 安全可靠** | 本地存储、2FA 支持、代理保护、风险监控 |
### 📊 功能一览
```
┌─────────────────────────────────────────────────────────────┐
│ Telegram MCP Complete │
├─────────────────────────────────────────────────────────────┤
│ 🤖 MCP 服务器 │
│ ├─ 123 个 AI 工具 │
│ ├─ 消息发送/接收/转发/编辑/删除 │
│ ├─ 群组/频道/聊天管理 │
│ ├─ 联系人/用户/封禁/拉黑 │
│ └─ 文件/图片/视频/语音/贴纸 │
│ │
│ 🌐 Web Dashboard │
│ ├─ 多账号管理（状态实时监控） │
│ ├─ 代理配置（全局 + 独立） │
│ ├─ 定时任务（Cron + 精确时间） │
│ ├─ 消息模板（变量替换） │
│ ├─ 健康监控（风险识别） │
│ └─ 操作日志（完整记录） │
│ │
│ 🎯 高级功能 │
│ ├─ AI 智能润色（情感优化、内容扩写） │
│ ├─ 批量发送（好友 + 陌生人用户名） │
│ ├─ 自动去重（用户名验证、重复过滤） │
│ ├─ 发送间隔（500ms - 50s 可调） │
│ └─ 定时触发（仅一次/每天/每周/工作日） │
└─────────────────────────────────────────────────────────────┘
```
---
## ⚡ 快速开始
### 方式一：扫码登录（推荐）
```bash
# 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`
```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 一键部署：
```bash
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（推荐）
```bash
git clone https://github.com/you922/telegram-mcp.git
cd telegram-mcp
docker-compose up -d
```
### 手动部署
```bash
git clone https://github.com/you922/telegram-mcp.git
cd telegram-mcp
pip install -r requirements.txt
python dashboard.py
```
### 服务器部署
```bash
# 后台运行
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
### 开发环境
```bash
# 克隆仓库
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](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...
```
---
## 👥 贡献者
感谢所有为本项目做出贡献的人！
<!--  -->
---
## 🙏 致谢
感谢以下开源项目：
- [Telethon](https://github.com/LonamiWebs/Telethon) - Telegram MTProto API
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 协议框架
- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Web 框架
- [Vue.js](https://vuejs.org/) - 渐进式前端框架
---
## 🔗 相关链接
- 📖 [MCP 协议规范](https://modelcontextprotocol.io/)
- 📚 [Telegram API 文档](https://core.telegram.org/api)
- 🔧 [Claude Code 文档](https://claude.ai/code/docs)
- 📖 [Telethon 文档](https://docs.telethon.dev/)
---
<div align="center">
**如果这个项目对你有帮助，请给一个 ⭐️ Star!**
[⭐ Star](https://github.com/you922/telegram-mcp/stargazers) •
[🍴 Fork](https://github.com/you922/telegram-mcp/network/members) •
[🐛 报告问题](https://github.com/you922/telegram-mcp/issues) •
[💬 讨论](https://github.com/you922/telegram-mcp/discussions)
---
**灵感来源:** [KT智能拓客](https://ktfy8888.com) | [@ktfy8888](https://t.me/ktfy8888)
---
**[🔝 返回顶部](#-telegram-mcp-complete)**
Made with ❤️ by [you922](https://github.com/you922)
</div>
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessSyncing