Telegram MCP Server

Telegram MCP 服务

一个功能强大的 Telegram 集成服务，通过 MCP（多客户端协议）提供联系人管理、消息发送和频道信息检索等多种工具。

功能

• 联系人管理

  • 获取联系人列表
  • 搜索联系人
  • 获取最近互动记录

• 消息

  • 按姓名或电话号码向联系人发送消息
  • 按日期范围筛选聊天记录
  • 查看最近互动记录

• 频道功能

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

先决条件

• 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

2. 安装所需依赖项：

uv venv .venv  # Create a virtual environment
source .venv/bin/activate  # Activate it (Linux/macOS)
.\venv\Scripts\activate  # Activate it (Windows)
uv pip install .

3. 获取你的 Telegram API ID 和 API Hash：

• 访问 https://my.telegram.org
• 使用你的电话号码登录
• 点击“API development tools”
• 填写所需字段（应用标题和简称可任意填写）
• 提交后，你将看到 API ID 和 API Hash

4. 在项目根目录中创建 .env 文件，并填入你的 Telegram 凭据：

TG_API_ID=your_api_id
TG_API_HASH=your_api_hash
phone=your_phone_number  # Format: +1234567890

5. 首次使用时进行 Telegram 身份验证

uv run telegram_auth.py

出现提示时，输入你通过 Telegram 收到的验证码。

与 Cursor/Claude Desktop 集成

复制以下 json，并填入相应的 {{PATH}} 值：

{
  "mcpServers": {
    "telegram": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}\\telegram-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

对于 Claude，将其保存为 claude_desktop_config.json，并放在 Claude Desktop 配置目录中：

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

对于 Cursor，将其保存为 mcp.json，并放在 Cursor 配置目录中：

~/.cursor/mcp.json

工具文档

get_contacts()

返回所有 Telegram 联系人的列表，包括姓名、电话号码和用户名。

send_message_by_identifier(identifier: str, message: str)

向通过姓名或电话号码标识的联系人发送消息。

• identifier：联系人的姓名或电话号码
• message：要发送的文本消息

get_last_interaction(identifier: str)

返回与指定联系人最近交换的消息。

• identifier：联系人的姓名或电话号码

get_chat_history(identifier: str, start_date: str = None, end_date: str = None, limit: int = 20)

检索指定时间范围内与联系人的聊天记录。

• identifier：联系人的姓名或电话号码
• start_date：可选的开始日期（YYYY-MM-DD）
• end_date：可选的结束日期（YYYY-MM-DD）
• limit：要返回的最大消息数量

get_channel_posts(channel_name: str, start_date: str = None, end_date: str = None, limit: int = 20)

获取 Telegram 频道的帖子。

• channel_name：频道用户名或名称
• start_date：可选的开始日期（YYYY-MM-DD）
• end_date：可选的结束日期（YYYY-MM-DD）
• limit：要返回的最大帖子数量

错误处理

该服务包含全面的错误处理，涵盖：

• 无效凭据
• 网络问题
• 速率限制
• 无效参数
• 权限错误

安全注意事项

• 安全存储 API 凭据
• 切勿分享你的 .env 文件
• 在生产环境中使用环境变量
• 在生产环境中实施速率限制
• 监控使用情况并实施日志记录

贡献

1. Fork 代码库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

致谢

• 感谢 Telethon 库提供 Telegram API 集成
• 感谢 FastMCP 提供服务框架