🚀 Telegram MCP 服务器指南

Telegram MCP 服务器作为连接 Telegram API 与 AI 助手（如 Claude Desktop）的桥梁，借助一系列工具，让 AI 助手能与 Telegram 的消息及功能实现交互。

⚠️ 重要提示

• 使用 Telegram API 时，请严格遵守其条款和条件。
• 确保您的 API 密钥和其他敏感信息的安全，避免泄露。

🚀 快速开始

先决条件

• 安装并配置 uv 工具
• 获取 Telegram 开发者账号
• 创建新的 Telegram 应用程序（用于获取 API ID 和 HASH）

安装步骤

1. 使用以下命令克隆仓库：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 在终端中运行服务器：

   cd mcp-telegram
   uv run mcp-telegram
   

3. 通过以下命令获取帮助信息：

   uv run mcp-telegram --help
   

更新步骤

uv sync

卸载步骤

uv uninstall mcp-telegram

✨ 主要特性

MCP 协议

MCP（Model Context Protocol）是一种用于 AI 应用程序与外部工具和服务之间通信的协议。通过 MCP，AI 助手可以：

• 操作 Telegram 账号
• 发送和接收消息
• 管理对话
• 使用 Telegram 的高级功能

服务器功能

已实现的功能

• 列出对话（支持按未读筛选）
• 发送和接收消息
• 创建新对话
• 获取聊天历史记录
• 操作 Telegram 文件和媒体

待完成的功能

• 群组管理
• 通道管理
• 定期任务
• API 日志记录

💻 使用示例

实际应用场景

创建未读消息摘要

使用 MCP 服务器从 Telegram 收取未读消息，并在 Claude Desktop 中生成摘要。

自动回复机器人

配置服务器工具以实现自动消息响应功能。

批量处理聊天记录

使用 MCP 服务器导出和管理大量聊天数据。

📦 安装指南

安装步骤

1. 使用以下命令克隆仓库：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 在终端中运行服务器：

   cd mcp-telegram
   uv run mcp-telegram
   

3. 通过以下命令获取帮助信息：

   uv run mcp-telegram --help
   

更新步骤

uv sync

卸载步骤

uv uninstall mcp-telegram

📚 详细文档

配置指南

Telegram API 配置

1. 登录您的 Telegram 账号，进入开发者工具界面。
2. 创建新的应用程序，并获取 API ID 和 API HASH。

Claude Desktop 配置

编辑配置文件（通常位于 ~/.config/claude/tools.yaml），添加以下内容：

full/path/to/uv: &uvcli
  cli: uv
  args:
    - run
    - mcp-telegram

确保路径正确无误。

开发指南

入门步骤

1. 克隆仓库：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 安装依赖项：

   uv sync
   

3. 运行服务器并查看帮助信息：

   uv run mcp-telegram --help
   

添加新工具

1. 在 src/mcp_telegram/tools.py 中创建新类：

   class NewTool(Tool):
       """描述新工具的功能"""
       async def _run(self, args: List[str], stdin: Optional[bytes]) -> Tuple[int, bytes]:
           # 实现具体功能
   

2. 使用以下装饰器注册工具：

   @toolkit_register
   class NewTool(Tool):
       pass
   

调试方法

终端调试

运行以下命令以查看日志信息：

uv run mcp-telegram --log=all

Inspector 工具

使用以下命令启动调试工具：

uv inspect mcp-telegram

故障排除

连接问题

1. 检查 uv 二进制文件路径是否正确。
2. 确保服务器已成功运行。

日志信息

查看日志以获取更多信息：

uv run mcp-telegram --log=all

通过以上指南，您可以轻松配置和使用 Telegram MCP 服务器。如需进一步帮助，请参考官方文档或联系开发者社区。