Telegram MCP 服务器

• Telegram MCP 服务器
  • 关于
  • 什么是 MCP？
  • 这个服务器是做什么的？
  • 实际用例
  • 先决条件
  • 安装
  • 配置
    • Telegram API 配置
    • Claude桌面配置
    • 电报配置
  • 发展
    • 入门
    • 在终端中调试服务器
    • 在检查器中调试服务器
  • 故障排除
    • 消息“无法连接到 MCP 服务器 mcp-telegram”

关于

该服务器是 Telegram API 和 AI 助手之间的桥梁，基于模型上下文协议。

重要提示：使用此服务器前，请确保您已阅读并理解Telegram API 服务条款。任何滥用 Telegram API 的行为都可能导致您的帐户被暂停。

什么是 MCP？

模型上下文协议 (MCP) 是一个允许 AI 应用（例如 Claude Desktop）连接到外部工具和数据源的系统。它为 AI 助手提供了一种清晰、安全的方式，使其能够使用本地服务和 API，同时保持用户的控制权。

这个服务器是做什么的？

到目前为止，服务器只提供对 Telegram API 的只读访问权限。

• [x] 获取对话列表（聊天、频道、群组）
• [x] 获取给定对话框中的（未读）消息列表
• [ ] 将频道标记为已读
• [ ] 按日期和时间检索消息
• [ ] 下载媒体文件
• [ ] 获取联系人列表
• [ ] 起草消息
• ...

实际用例

• [x] 创建未读消息的摘要
• [ ] 查找生日即将到来的联系人并安排问候
• [ ] 查找关于给定主题的讨论，总结它们并提供链接列表

先决条件

• uv工具

安装

[!NOTE] 如果您已经安装了服务器，则可以使用uv tool upgrade --reinstall命令进行更新。

[!NOTE] 如果要删除服务器，请使用uv tool uninstall mcp-telegram命令。

配置

Telegram API 配置

在使用服务器之前，您需要连接到 Telegram API。

1. 从Telegram API获取 API ID 和哈希值
2. 运行以下命令：
   mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
   输入您从 Telegram 收到的代码以连接到 API。如果您启用了双因素身份验证，则可能需要密码。

[!NOTE] 要从 Telegram API 注销，请使用mcp-telegram logout命令。

Claude桌面配置

配置 Claude Desktop 以识别 Exa MCP 服务器。

1. 打开Claude桌面配置文件：
   • 在 MacOS 中，配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json
   • 在 Windows 中，配置文件位于%APPDATA%\Claude\claude_desktop_config.json

   **注意：**您还可以在 Claude Desktop 应用程序的设置中找到 claude_desktop_config.json

2. 添加服务器配置
   { "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "<your-api-id>", "TELEGRAM_API_HASH": "<your-api-hash>", }, } } } }

电报配置

在使用 Telegram 的 API 之前，您需要获取自己的 API ID 和哈希值：

1. 使用要使用的开发者帐户的电话号码登录您的 Telegram 帐户。
2. 单击 API 开发工具。
3. 将出现“创建新应用程序”窗口。填写您的应用程序详细信息。无需输入任何 URL，目前只有前两个字段（应用程序标题和简称）可以稍后更改。
4. 最后点击“创建应用程序”。请记住，您的 API 哈希值是保密的，Telegram 不会允许您撤销它。请勿将其发布到任何地方！

发展

入门

1. 克隆存储库
2. 安装依赖项
   uv sync
3. 运行服务器
   uv run mcp-telegram --help

可以将工具添加到src/mcp_telegram/tools.py文件中。

如何添加新工具：

1. 创建一个继承自 ToolArgs 的新类
   class NewTool(ToolArgs): """Description of the new tool.""" pass
   该类的属性将用作该工具的参数。类的文档字符串将用作工具的描述。
2. 为新类实现 tool_runner 函数
   @tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: pass
   该函数应返回 TextContent、ImageContent 或 EmbeddedResource 的序列。该函数应为异步函数，并接受新类的单个参数。
3. 完成！重启客户端，新工具就可以使用了。

验证可以通过 Claude Desktop 或直接运行工具来完成。

在终端中调试服务器

要直接运行该工具，请使用以下命令：

在检查器中调试服务器

MCP 检查器是一款使用精美 UI 帮助调试服务器的工具。要运行它，请使用以下命令：

[!WARNING] 不要忘记在检查器中定义环境变量 TELEGRAM_API_ID 和 TELEGRAM_API_HASH。

故障排除

消息“无法连接到 MCP 服务器 mcp-telegram”

如果您在 Claude Desktop 中看到消息“无法连接到 MCP 服务器 mcp-telegram”，则表示服务器配置不正确。

请尝试以下操作：

• 在配置文件中使用uv二进制文件的完整路径
• 检查配置文件中克隆存储库的路径