Telegram MCP Complete

AI 驱动的 Telegram 多账号管理神器
123+ MCP 工具 | 一键群发 | 定时任务 | AI 智能润色 | Web 后台

💡 灵感来源

本项目灵感来自 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: 支持两种登录方式：

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

Q: Session 安全吗？

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

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

Q: 如何使用代理？

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

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

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

Q: 定时任务怎么使用？

A: 在 Dashboard 中：

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

Q: AI 润色功能怎么用？

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

创建定时任务时选择"AI 执行"模式
到达执行时间后，任务进入"待润色"队列
AI 通过 get_pending_ai_tasks 获取任务
AI 使用 polish_message 或 expand_message 润色消息
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

🤝 贡献指南

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

如何贡献

🍴 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

MCP Servers