MCP Servers

Telegram MCP Complete

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

README

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

<h1 align="center">Telegram MCP Complete</h1>

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

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

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

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

</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 工具列表

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

</details>

工具	描述
`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>

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

</details>

工具	描述
`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>

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

</details>

工具	描述
`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>Q: 支持哪些登录方式？</summary>

A: 支持两种登录方式：

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

</details>

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

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

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

</details>

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

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

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

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

</details>

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

A: 在 Dashboard 中：

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

</details>

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

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

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

</details>

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

A: 可以！支持：

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

</details>

<details> <summary>Q: 支持 Docker 部署吗？</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

🤝 贡献指南

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

如何贡献

🍴 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

</div>

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured