💡 灵感来源

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

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

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

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

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

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

工具	描述
`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润色]                                        │  │
│  │  [禁用] [删除]                                             │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

❓ 常见问题

A: 支持两种登录方式：

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

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

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

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

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

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

A: 在 Dashboard 中：

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

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

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

A: 可以！支持：

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

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

🤝 贡献指南

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

如何贡献

🍴 Fork 本仓库
🌟 创建你的特性分支 (git checkout -b feature/AmazingFeature)
💾 提交更改 (git commit -m 'Add some AmazingFeature')
📤 推送到分支 (git push origin feature/AmazingFeature)
🔀 开启 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 - 渐进式前端框架

🔗 相关链接

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

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

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

🔝 返回顶部

Made with ❤️ by you922