项目简介

TGMCP 是一个 Python 包，实现了 Model Context Protocol (MCP)，作为 AI 智能体与 Telegram 账户之间的桥梁。它允许 AI 访问您的 Telegram 数据并执行操作，例如发送和接收消息、管理联系人和群组等。

主要功能点

聊天操作： 获取聊天列表、读取和发送消息、归档/取消归档、静音/取消静音聊天。
联系人管理： 列出、搜索、添加、删除、拉黑/解除拉黑联系人。
群组管理： 创建群组/频道、邀请成员、离开聊天、获取成员/管理员/被封禁用户列表、编辑群组信息（标题、照片）。
消息操作： 获取消息、转发、编辑、删除、置顶/取消置顶消息、标记已读、回复消息、搜索消息。
媒体处理： 发送文件、下载媒体、发送语音/贴纸/GIF。
个人资料管理： 获取个人信息、更新资料（姓名、简介）、设置/删除头像、获取隐私设置、获取用户状态。
管理功能： 提升/撤销管理员权限、封禁/解封用户。

安装步骤

确保您已安装 Python 3.8 或更高版本。

使用 pip 从 PyPI 安装：

pip install tgmcp

服务器配置

TGMCP 作为 MCP 服务器运行，通常由您的 MCP 客户端（如 VS Code 扩展）启动和管理。您需要在 MCP 客户端的配置中指定如何启动 TGMCP。

典型的 MCP 客户端配置会包含一个 JSON 对象，描述名为 'mcp-telegram' 的服务器。此配置应包含：

'command': 启动 TGMCP 服务器的命令，通常是 'tgmcp' 或 'python -m tgmcp'。
'args': 传递给命令的参数，例如 'start'。
'env': 一组环境变量，用于配置 Telegram API 凭据和 TGMCP 的行为。

重要的环境变量包括：

'TELEGRAM_API_ID'：您的 Telegram API ID。
'TELEGRAM_API_HASH'：您的 Telegram API Hash。
'TELEGRAM_SESSION_STRING'：推荐使用会话字符串进行认证，这是最可靠和便携的方式。
'TELEGRAM_SESSION_NAME'：如果您不使用会话字符串，可以使用会话文件，这是会话文件的名称。
'MCP_NONINTERACTIVE': 设置为 'true' 以在非交互模式下运行，适合由客户端启动。
'TGMCP_ENABLE_*_TOOLS': 可选，用于选择性地启用或禁用特定的工具集（例如 'TGMCP_ENABLE_CHAT_TOOLS=true'）。

在您的 MCP 客户端配置中，您需要填写您的实际凭据，例如：

// MCP 客户端配置示例 (JSON 格式的片段)
{
  "mcp": {
    "servers": {
      "mcp-telegram": {
        "command": "tgmcp", // 或 "python -m tgmcp"
        "args": ["start"],
        "env": {
          "TELEGRAM_API_ID": "您的 API ID",
          "TELEGRAM_API_HASH": "您的 API Hash",
          "TELEGRAM_SESSION_STRING": "您的会话字符串 (推荐使用)",
          // 或者如果您使用文件会话：
          // "TELEGRAM_SESSION_NAME": "您的会话名称",
          "MCP_NONINTERACTIVE": "true",
          
          // 可选：启用/禁用特定工具集
          // "TGMCP_ENABLE_CHAT_TOOLS": "true",
          // ...
        }
      }
    }
  }
}

首次认证：

在 MCP 客户端能够成功启动 TGMCP 服务器之前，您需要先进行一次 Telegram 认证。推荐通过生成会话字符串来完成。打开终端并运行：

python -m tgmcp.session_string_generator

按照提示输入您的手机号和验证码，生成会话字符串后，将其添加到您的 MCP 客户端配置的 'env' 中作为 'TELEGRAM_SESSION_STRING' 的值。

如果您选择使用会话文件（不推荐用于非交互式 MCP 服务器），可以运行：

python -m tgmcp.authenticate

并按照提示操作。这会在当前目录下生成一个 '.session' 文件。

基本使用方法

一旦 TGMCP 配置在您的 MCP 客户端中，并且您已经完成了 Telegram 认证，客户端应该能够自动启动 TGMCP 服务器。

您也可以手动在终端中启动服务器（主要用于调试）：

python -m tgmcp

该命令会启动 TGMCP 服务器，它将通过标准输入输出 (Stdio) 与 MCP 客户端通信。

您的 AI 智能体或 LLM 客户端现在应该能够通过 MCP 协议调用 TGMCP 提供的各种工具来与您的 Telegram 账户进行交互了。例如，AI 可以调用 'send_message' 工具来发送消息，调用 'list_chats' 工具来获取聊天列表等。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息