通过模型上下文协议（MCP）将大型语言模型连接到 Telegram。
该服务器由Telethon构建，允许 AI 代理与 Telegram 交互，从而实现使用MTProto发送/编辑/删除消息、搜索聊天、管理草稿、下载媒体等功能。
🚀 入门
先决条件
安装
安装mcp-telegram CLI 工具：
⚙️ 使用方法
重要提示：使用此工具前，请确保您已阅读并理解 Telegram 的服务条款。滥用此工具可能会导致账户被限制。
mcp-telegram命令行工具是您的入口点。
登录
首先，使用您的 Telegram 帐户进行身份验证：
此交互式命令将提示您输入：
- **API ID 和 API Hash：**从my.telegram.org/apps获取。
- **电话号码：**您的 Telegram 注册电话号码（国际格式，例如
+1234567890）。 - **验证码：**首次登录时发送到您的 Telegram 帐户。
- **2FA 密码：**如果您启用了双因素身份验证。
您的凭证安全地存储在会话文件中以供将来使用。
警告：请保持 API 凭据的私密性，切勿公开分享
[!NOTE] 使用
mcp-telegram logout从当前会话注销或mcp-telegram clear-session删除所有存储的会话数据。
连接到 MCP 服务器
要将 MCP Telegram 与 Claude Desktop 或 Cursor 等 MCP 客户端配合使用，您需要配置 MCP 服务器。配置过程因客户端和操作系统而异。
详细设置说明请参考：
配置文件应该包含：
配置路径因 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 交互的工具的完整列表：
📨 消息传递工具
| 工具 | 描述 |
|---|---|
send_message | ✉️ 向任何用户、群组或频道发送短信或文件 |
edit_message | ✏️ 修改之前发送的消息内容 |
delete_message | 🗑️ 删除一条或多条消息 |
get_messages | 📜 使用高级过滤选项检索消息历史记录 |
🔍 搜索和导航
| 工具 | 描述 |
|---|---|
search_dialogs | 🔎 通过名称或用户名查找用户、群组和频道 |
message_from_link | 🔗 使用 Telegram 链接访问特定消息 |
📝 草稿管理
| 工具 | 描述 |
|---|---|
get_draft | 📋 查看任何聊天的当前消息草稿 |
set_draft | ✍️ 创建或清除消息草稿 |
📂 媒体处理
| 工具 | 描述 |
|---|---|
media_download | 📸 从消息中下载照片、视频和文档 |
[!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文件。