<中文翻译> mcp-电报服务器

Name: mcp-电报服务器
Author: dryeab

作者：dryeab209 星标更新：2025-06-15

项目介绍

<div align="center"> <img src="logo.png" alt="MCP Telegram Logo" width="150"/> <h2 style="margin-top: 0">通过MCP让大型语言模型控制您的Telegram</h2> </div> <div align="center"> <a href="https://github.com/dryeab/mcp-telegram/stargazers"><img src="https://img.shields.io/github/stars/dryeab/mcp-telegram?style=social" alt="GitHub stars"></a> <a href="https://badge.fury.io/py/mcp-telegram"><img src="https://badge.fury.io/py/mcp-telegram.svg" alt="PyPI version"></a> <a href="https://x.com/dryeab"><img src="https://img.shields.io/twitter/follow/dryeab?style=social" alt="Twitter Follow"></a> </div> <h3></h3>

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

本项目基于Telethon构建，允许AI代理与Telegram进行交互，实现发送/编辑/删除消息、搜索聊天记录、管理草稿、下载媒体等功能，使用MTProto协议。

🚀 开始使用
- 先决条件
- 安装
⚙️ 使用方法
- 登录
- 连接到MCP服务器
🧰 可用工具
🛠️ 故障排除
🤝 贡献
📝 许可证

</details>

🚀 开始使用

先决条件

Python 3.10 或更高版本
安装uv，请参考官方uv指南。

安装

安装mcp-telegram命令行工具：

uv tool install mcp-telegram

⚙️ 使用方法

[!重要] 在使用此工具之前，请确保您已阅读并理解了Telegram的服务条款。滥用此工具可能导致账户受限。

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

mcp-telegram --help # 查看所有命令

连接到MCP服务器

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

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

配置文件应包含：

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* 如果客户端无法找到命令，请使用完整路径（例如"/usr/local/bin/mcp-telegram"）。请参见下面的重要部分以获取完整路径说明。*/,
      "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`	📸 下载来自消息的照片、视频和文档

[!注意] 有关详细参数信息和示例用法，请在终端中运行m_ c p-telegram tools。

🛠️ 故障排除

数据库锁定错误

使用相同的会话文件运行多个mcp-telegram实例可能会导致由于Telethon的SQLite会话存储引起的“数据库被锁定”错误。请确保一次只有一个实例使用会话文件。

<details> <summary>强制停止现有进程</summary>

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

macOS / Linux: pkill -f "mcp-telegram"
Windows: taskkill /F /IM mcp-telegram.exe /T （检查任务管理器以获取确切的进程名称）