Telegram MCP 服务器

• Telegram MCP 服务器
  • 关于
  • 什么是MCP？
  • 这个服务器做什么？
  • 实际用例
  • 前提条件
  • 安装
  • 配置
    • Telegram API 配置
    • Claude Desktop 配置
    • Telegram 配置
  • 开发
    • 开始使用
    • 在终端调试服务器
    • 在Inspector中调试服务器
  • 故障排除
    • 消息“无法连接到MCP服务器mcp-telegram”

关于

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

[!IMPORTANT] 在使用此服务器之前，请确保您已经阅读并理解了Telegram API服务条款。 Telegram API的任何滥用行为可能导致您的账户被暂停。

<a href="https://glama.ai/mcp/servers/484jega1au"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=1132038992,2970626959&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Telegram Server MCP 服务器" /> </a>

什么是MCP？

模型上下文协议（MCP）是一个系统，允许像Claude Desktop这样的AI应用程序连接到外部工具和数据源。它提供了一种清晰且安全的方式，使AI助手能够与本地服务和API进行交互，同时保持用户控制权。

这个服务器做什么？

目前，该服务器提供了对Telegram API的只读访问权限。

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

实际用例

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

前提条件

• uv工具

安装

uv tool install git+https://github.com/sparfenyuk/mcp-telegram

[!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 Desktop 配置

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

1. 打开Claude Desktop配置文件：

   • 在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 配置

在使用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):
       """新工具的描述。"""
       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或直接运行工具来完成。

在终端调试服务器

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

# 列出所有可用工具
uv run cli.py list-tools

# 运行具体工具
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

在Inspector中调试服务器

MCP Inspector是一个帮助通过漂亮的UI调试服务器的工具。要运行它，使用以下命令：

npx @modelcontextprotocol/inspector uv run mcp-telegram

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

故障排除

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

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

尝试以下操作：

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