Mcp Telegram

通过 Model Context Protocol (MCP) 将大语言模型连接到 Telegram。

此 MCP 服务基于 Telethon 构建，可让 AI Agent 与 Telegram 交互，使用 MTProto 发送、编辑和删除消息、搜索聊天、管理草稿、下载媒体等。

---

目录

• 🚀 快速开始
  • 先决条件
  • 安装
• ⚙️ 使用方法
  • 登录
  • 连接到 MCP 服务
• 🧰 可用工具
  • 📨 消息工具
  • 🔍 搜索与导航
  • 📝 草稿管理
  • 📂 媒体处理
• 🛠️ 故障排除
• 🤝 参与贡献
• 📝 许可证

---

🚀 快速开始

先决条件

• Python 3.10 或更高版本
• uv 请参阅 uv 官方指南进行安装。

安装

安装 mcp-telegram 命令行工具：

uv tool install mcp-telegram

⚙️ 使用方法

重要

使用此工具前，请确保已阅读并理解 Telegram 的服务条款。滥用此工具可能导致账户受限。

mcp-telegram 命令行工具是你的入口。

mcp-telegram --help # See all commands

登录

首先，使用你的 Telegram 账户进行身份验证：

mcp-telegram login

此交互式命令会提示你提供：

• API ID 和 API Hash： 可从 my.telegram.org/apps 获取。
• 电话号码： 你在 Telegram 注册的电话号码（国际格式，例如 +1234567890）。
• 验证码： 首次登录时会发送到你的 Telegram 账户。
• 两步验证密码： 如果你启用了两步验证。

你的凭据会安全地存储在会话文件中，以供日后使用。

警告

妥善保管 API 凭据，切勿公开分享。

说明

使用 mcp-telegram logout 退出当前会话，或使用 mcp-telegram clear-session 删除所有已存储的会话数据。

连接到 MCP 服务

要通过 Claude Desktop 或 Cursor 等 MCP 客户端使用 MCP Telegram，你需要配置 MCP 服务。配置过程因客户端和操作系统而异。

如需详细的设置说明，请参阅：

• Claude Desktop MCP 设置指南
• Cursor MCP 文档

配置文件应包含：

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

说明

配置路径因操作系统和客户端而异。例如：

• macOS：~/Library/Application Support/Claude/ 或 ~/.cursor/
• Windows：%APPDATA%\Claude\ 或 %APPDATA%\Cursor\

重要

如果客户端无法执行 mcp-telegram，尽管它可以在终端中访问，请尝试使用可执行文件的完整路径。你可以在终端中运行 which mcp-telegram（macOS/Linux）或 where mcp-telegram（Windows）来查找该路径。将配置中的 command 值替换为完整路径。

保存配置文件后，重启应用程序。

🧰 可用工具

以下是你可以通过 MCP 与 Telegram 交互的完整工具列表：

📨 消息工具

工具	描述
send_message	✉️ 向任何用户、群组或频道发送文本消息或文件
edit_message	✏️ 修改之前发送的消息内容
delete_message	🗑️ 删除一条或多条消息
get_messages	📜 获取消息历史记录，并使用高级筛选选项

🔍 搜索与导航

工具	描述
search_dialogs	🔎 按名称或用户名查找用户、群组和频道
message_from_link	🔗 使用 Telegram 链接访问特定消息

📝 草稿管理

工具	描述
get_draft	📋 查看任意聊天当前的消息草稿
set_draft	✍️ 创建或清除消息草稿

📂 媒体处理

工具	描述
media_download	📸 从消息中下载照片、视频和文档

说明

如需详细的参数信息和使用示例，请在终端中运行 mcp-telegram tools。

🛠️ 故障排除

数据库锁定错误

使用_同一个会话文件_运行多个 mcp-telegram 实例，可能会因 Telethon 的 SQLite 会话存储而导致 database is locked 错误。请确保同一时间只有一个实例使用某个会话文件。

强制停止现有进程

如果需要停止可能卡住的进程：

• macOS / Linux： pkill -f "mcp-telegram"
• Windows： taskkill /F /IM mcp-telegram.exe /T（在任务管理器中查看准确的进程名称）

🤝 参与贡献

欢迎贡献！如果你想帮助改进 MCP Telegram，欢迎提交问题、功能请求或拉取请求。你的反馈和贡献有助于让这个项目更好地服务所有人。

📝 许可证

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

---