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  # 创建一个虚拟环境
source .venv/bin/activate  # 激活它 (Linux/macOS)
.\venv\Scripts\activate  # 激活它 (Windows)
uv pip install

3. 在项目根目录中创建一个 .env 文件，其中包含您的 Telegram 凭据:

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

与 Cursor/Claude Desktop 集成

复制下面的 json，并使用适当的 {{PATH}} 值:

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // 运行 `which uv` 并将输出放在这里
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd 进入 repo，运行 `pwd` 并在此处输入输出 + "/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，用于服务器框架