Tg MCP

🚀 MCP 电报服务器

MCP 电报服务器是一款功能强大的电报服务实现方案，借助简洁的 API 接口，为用户提供消息搜索、发送以及聊天管理等功能，极大提升了电报使用的便捷性与效率。

加入我们的电报讨论组，即可参与社区讨论，获取项目支持与最新更新。

🚀 快速开始

在使用 MCP 电报服务器之前，您需要满足以下先决条件：

• Python 3.x
• 电报 API 凭证（API ID，API Hash）
• MCP 兼容环境（如 Cursor IDE）

✨ 主要特性

• 多模式消息搜索：
  • 基本文本搜索：可快速定位包含特定文本的消息。
  • 带有自定义过滤器的高级搜索：支持根据多种条件筛选消息。
  • 使用正则表达式的基于模式的搜索：满足复杂的消息查找需求。
• 聊天管理：
  • 列出可用对话：方便用户查看所有聊天会话。
  • 发送带有可选回复支持的消息：支持对特定消息进行回复。
  • 生成消息链接：便于分享特定消息。
• 分析和数据：
  • 聊天统计信息和分析：深入了解聊天数据。
  • 聊天数据导出功能：方便用户备份和处理聊天数据。
• 强大的错误处理和日志记录：确保系统稳定运行，便于排查问题。
• 基于 MCP（模型控制协议）架构构建：具备良好的扩展性和兼容性。

📦 安装指南

1. 克隆仓库并进入项目目录：

git clone https://github.com/leshchenko1979/tg_mcp.git
cd tg_mcp

2. 安装依赖项：

pip install -r requirements.txt

3. 在根目录下创建一个.env文件，包含您的电报凭证：

API_ID=your_api_id
API_HASH=your_api_hash
PHONE_NUMBER=+123456789

4. 运行设置脚本来与电报认证：

python setup_telegram.py

这将创建一个会话文件（mcp_telegram_search.session），其中存储您的电报会话数据。

📚 详细文档

Cursor配置

要将此服务器与 Cursor IDE 一起使用：

1. 在.cursor目录中创建一个mcp.json文件，内容如下：

{
  "mcpServers": {
    "telegram_server": {
      "type": "local",
      "config": {
        "env_file": ".env"
      }
    }
  }
}

2. 启动 Cursor 并连接到新的 MCP 服务器。

使用说明

计算消息哈希

mcp TelegramServer \
    --hash "Hello, World!"

批量处理聊天记录

for message in $(seq 1 100); do
    mcp TelegramServer \
        --send "Message $message"
done

项目结构

项目目录/
├── setup_telegram.py         # 电报设置脚本
├── requirements.txt          # 项目依赖项
├── .env                      # 环境变量（创建此文件）
├── logs/                    # 日志文件目录
├── LICENSE                 # MIT 许可证
└── src/
    ├── server.py            # 主服务器逻辑
    └── utils.py           # 辅助函数和工具

注意：在认证后会生成*.session 和 *.session-journal 文件

依赖项

项目依赖以下主要包：

loguru          # 日志记录
aiohttp         # 异步 HTTP
mcp[cli]        # 模型控制协议
telethon>=1.34.0  # 电报客户端
python-dotenv>=1.0.0  # 环境管理

📄 许可证

此项目根据 MIT 许可证发布，详细信息请参阅LICENSE文件。