Telegram MCP Server

基本能力

产品定位

Telegram MCP Server 是一个用于集成 Telegram 功能的服务器，主要用于联系人管理、消息发送和频道信息检索。

核心功能

• 联系人管理
• 获取联系人列表
• 搜索联系人

• 获取最后互动记录

• 消息功能

• 通过姓名或电话号码发送消息
• 获取带日期范围筛选的聊天历史

• 查看最后互动记录

• 频道功能

• 从频道获取帖子
• 搜索频道
• 查看频道信息
• 按日期范围筛选帖子

适用场景

• 自动化 Telegram 消息发送
• 管理大量联系人
• 监控和检索频道信息
• 集成到其他应用程序中实现 Telegram 功能

工具列表

• get_contacts()：返回所有 Telegram 联系人的列表，包括姓名、电话号码和用户名。
• send_message_by_identifier(identifier: str, message: str)：通过姓名或电话号码向联系人发送消息。
• get_last_interaction(identifier: str)：返回与特定联系人最近交换的消息。
• get_chat_history(identifier: str, start_date: str = None, end_date: str = None, limit: int = 20)：检索指定时间范围内的聊天历史。
• get_channel_posts(channel_name: str, start_date: str = None, end_date: str = None, limit: int = 20)：从 Telegram 频道获取帖子。

常见问题解答

• 错误处理：服务器包括全面的错误处理，包括无效凭据、网络问题、速率限制、无效参数和权限错误。
• 安全考虑：建议安全存储 API 凭据，不要共享 .env 文件，在生产中使用环境变量，实施速率限制和日志记录。

使用教程

使用依赖

• Python 3.8 或更高版本
• Node.js 14 或更高版本（用于 npx 安装）
• Telegram API 凭据（api_id 和 api_hash）
• 一个 Telegram 账户

安装教程

1. 克隆仓库：

git clone https://github.com/yourusername/telegram-MCP-server.git
cd telegram-MCP-server

1. 安装所需依赖：

uv venv .venv  # 创建虚拟环境
source .venv/bin/activate  # 激活（Linux/macOS）
.\venv\Scripts\activate  # 激活（Windows）
uv pip install

1. 在项目根目录创建 .env 文件，包含你的 Telegram 凭据：

TG_API_ID=your_api_id
TG_API_HASH=your_api_hash
phone=your_phone_number  # 格式：+1234567890

调试方式

集成到 Cursor/Claude Desktop 时，确保路径配置正确。对于 Claude，将配置保存为 claude_desktop_config.json 在：

~/Library/Application Support/Claude/claude_desktop_config.json

对于 Cursor，保存为 mcp.json 在：

~/.cursor/mcp.json

许可证

该项目遵循 MIT 开源许可条款。