---

---

💡 灵感来源

本项目灵感来自 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 工具列表

💬 聊天管理 (6 个工具)

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

📝 消息操作 (29 个工具)

工具	描述
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	下载媒体文件
...	更多工具

👥 用户/联系人 (12 个工具)

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

👥 群组/频道 (29 个工具)

工具	描述
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	获取邀请链接
...	更多工具

📅 定时任务 (7 个工具)

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

📁 文件/媒体 (3 个工具)

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

工具总数：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润色]                                        │  │
│  │  [禁用] [删除]                                             │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

---

❓ 常见问题

Q: 支持哪些登录方式？

A: 支持两种登录方式：

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

Q: Session 安全吗？

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

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

Q: 如何使用代理？

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

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

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

Q: 定时任务怎么使用？

A: 在 Dashboard 中：

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

Q: AI 润色功能怎么用？

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

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

Q: 可以批量发送吗？

A: 可以！支持：

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

Q: 支持 Docker 部署吗？

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

docker-compose up -d

访问 http://localhost:8080

---

📁 项目结构

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...

---

👥 贡献者

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

---

🙏 致谢

感谢以下开源项目：

• Telethon - Telegram MTProto API
• FastMCP - MCP 协议框架
• FastAPI - 现代 Web 框架
• Vue.js - 渐进式前端框架

---

🔗 相关链接

• 📖 MCP 协议规范
• 📚 Telegram API 文档
• 🔧 Claude Code 文档
• 📖 Telethon 文档

---