MCP Telegram

通过模型上下文协议（MCP）将大型语言模型连接到 Telegram。

该服务器由Telethon构建，允许 AI 代理与 Telegram 交互，从而实现使用MTProto发送/编辑/删除消息、搜索聊天、管理草稿、下载媒体等功能。

• 🚀 入门

  • 先决条件

  • 安装

• ⚙️ 使用方法

  • 登录

  • 连接到 MCP 服务器

• 🧰 可用工具

  • 📨 消息传递工具

  • 🔍 搜索和导航

  • 📝 草稿管理

  • 📂 媒体处理

• 🛠️ 故障排除

• 🤝 贡献

• 📝 许可证

🚀 入门

先决条件

• Python 3.10 或更高版本

• uv通过官方 uv 指南安装。

安装

安装mcp-telegram CLI 工具：

uv tool install mcp-telegram

Related MCP server: Alchemy MCP Server

⚙️ 使用方法

重要提示：使用此工具前，请确保您已阅读并理解 Telegram 的服务条款。滥用此工具可能会导致账户被限制。

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

mcp-telegram --help # See all commands

登录

首先，使用您的 Telegram 帐户进行身份验证：

mcp-telegram login

此交互式命令将提示您输入：

• **API ID 和 API Hash：**从my.telegram.org/apps获取。

• **电话号码：**您的 Telegram 注册电话号码（国际格式，例如+1234567890 ）。

• **验证码：**首次登录时发送到您的 Telegram 帐户。

• **2FA 密码：**如果您启用了双因素身份验证。

您的凭证安全地存储在会话文件中以供将来使用。

警告：请保持 API 凭据的私密性，切勿公开分享

连接到 MCP 服务器

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

详细设置说明请参考：

• Claude Desktop MCP 设置指南

• 光标 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>"
      }
    }
  }
}

配置路径因 OS 和客户端而异。例如：

• 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 交互的工具的完整列表：

📨 消息传递工具

🔍 搜索和导航

📝 草稿管理

📂 媒体处理

[!Note] 有关详细的参数信息和示例用例，请在终端中运行mcp-telegram tools 。

🛠️ 故障排除

数据库锁定错误

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

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

• macOS / Linux： pkill -f "mcp-telegram"

• Windows： taskkill /F /IM mcp-telegram.exe /T （检查任务管理器以获取确切的进程名称）

🤝 贡献

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

📝 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。