使用说明

项目简介

Telegram MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在将 Telegram 的功能集成到支持 MCP 协议的 LLM 客户端（如 Claude 和 Cursor）中。它允许 LLM 通过标准化的工具访问您的 Telegram 消息记录、联系人信息，并执行发送消息等操作，从而增强 LLM 在 Telegram 场景下的应用能力。

该项目包含两个主要组件：

Telegram Bridge: 负责与 Telegram API 交互，同步消息数据到本地 SQLite 数据库，并提供 HTTP API 供 MCP Server 调用。
Telegram MCP Server: 实现了 MCP 协议，对外暴露一系列工具，LLM 客户端可以通过这些工具查询 Telegram 数据和发送消息。

主要功能点

搜索联系人 (search_contacts): 允许 LLM 根据名称或用户名搜索 Telegram 联系人。
列出消息 (list_messages): 允许 LLM 检索指定聊天或联系人的消息记录，支持按日期范围、发送者、关键词等过滤，并可选择返回上下文消息。
列出聊天 (list_chats): 允许 LLM 列出 Telegram 聊天列表，支持按名称、类型等过滤。
获取聊天信息 (get_chat): 允许 LLM 获取指定 ID 的聊天详细信息。
通过联系人获取私聊 (get_direct_chat_by_contact): 允许 LLM 通过联系人 ID 获取与其的私聊信息。
获取联系人的聊天列表 (get_contact_chats): 允许 LLM 获取包含特定联系人的所有聊天列表。
获取最近互动消息 (get_last_interaction): 允许 LLM 获取与特定联系人的最近一条消息。
获取消息上下文 (get_message_context): 允许 LLM 获取指定消息的前后几条消息，以理解上下文语境。
发送消息 (send_message): 允许 LLM 向指定的用户名或聊天 ID 发送 Telegram 消息。

安装步骤

克隆仓库

git clone https://github.com/Muhammad18557/telegram-mcp.git
cd telegram-mcp

创建并激活 Python 虚拟环境

python3 -m venv myenv
source myenv/bin/activate

安装依赖

pip install -r requirements.txt

获取 Telegram API 凭证
- 访问 https://my.telegram.org/auth
- 登录并进入 "API development tools"
- 创建一个新的应用，记录 API ID 和 API hash
配置 Telegram API 凭证
- 进入 'telegram-bridge' 目录：'cd telegram-bridge'
- 复制 '.env.example' 文件为 '.env'：'cp .env.example .env'
- 编辑 '.env' 文件，填入您的 Telegram API ID 和 API hash。
配置 MCP 服务器启动脚本路径
- 编辑 'run_telegram_server.sh' 文件，将 'BASE_DIR' 变量的值修改为您的 'telegram-mcp' 仓库的绝对路径。可以使用 'pwd' 命令获取当前仓库的绝对路径。

服务器配置

要将 Telegram MCP Server 集成到 MCP 客户端（如 Claude 或 Cursor），您需要配置客户端的 MCP 配置文件。以下是配置示例，请根据您的客户端类型选择相应的配置文件和路径。

Claude Desktop 配置 ( '~/Library/Application\ Support/Claude/claude_desktop_config.json' )

{
  "mcpServers": {
    "telegram": {
      "command": "/bin/bash",
      "args": [
        "{{BASE_DIR}}/run_telegram_server.sh"
      ]
    }
  }
}

Cursor 配置 ( '~/.cursor/mcp.json' )

{
  "mcpServers": {
    "telegram": {
      "command": "/bin/bash",
      "args": [
        "{{BASE_DIR}}/run_telegram_server.sh"
      ]
    }
  }
}

配置参数说明:

'"telegram"': 服务器名称，在客户端中用于标识和选择 Telegram 集成。
'"command"': 启动服务器的命令，这里使用 '/bin/bash' 来执行 shell 脚本。
'"args"': 传递给 'command' 的参数列表。
- '"{{BASE_DIR}}/run_telegram_server.sh"': 执行 'run_telegram_server.sh' 脚本，'{{BASE_DIR}}' 会被客户端替换为您的仓库根目录的绝对路径。

注意:

请确保 'run_telegram_server.sh' 脚本中的 'BASE_DIR' 变量已正确配置为您的仓库绝对路径。
将上述 JSON 配置保存到对应客户端的配置文件中，并确保文件路径正确。

基本使用方法

启动 Telegram Bridge 和 MCP Server: 'run_telegram_server.sh' 脚本会同时启动 Telegram Bridge 和 MCP Server。
重启 Claude Desktop 或 Cursor: 重启您的 MCP 客户端，客户端应该能够检测到并连接到 Telegram MCP Server。
在客户端中使用: 在 Claude 或 Cursor 中，您应该能够看到 Telegram 集成选项。通过自然语言指令，您可以指示 LLM 使用 Telegram 工具来搜索联系人、查询消息、发送消息等。例如，您可以对 Claude 说 "Search for messages from John about project updates in Telegram" 或 "Send a message to group 'Team Project' in Telegram saying 'Meeting postponed to tomorrow'"。

重要提示:

首次运行 Telegram Bridge 时，需要根据提示在终端中输入您的 Telegram 手机号码和验证码以完成身份验证。
首次同步消息记录可能需要一些时间，特别是当您的 Telegram 消息较多时。

关键词