AI导哈

Telegram MCP服务器

Telegram MCP服务器是一个连接Telegram API和AI助手的桥梁，基于Model Context Protocol，提供对Telegram API的只读访问，适用于消息摘要和联系人管理等场景。

  • by sparfenyuk
  • Python
  • 本地部署
  • 189 星标
  • 更新于
在 GitHub 查看 sparfenyuk/mcp-telegram

使用说明

电报MCP服务器

关于

该服务器是Telegram API和人工智能助手之间的桥梁，基于 模型上下文协议.

[！重要] 确保您已阅读并理解 电报API服务条款 在使用此服务器之前。 任何对Telegram API的滥用都可能导致您的帐户被暂停。

什么是MCP？

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

这个服务器做什么？

截至目前，服务器提供对Telegram API的只读访问。

  • [x] 获取对话列表（聊天、频道、组）
  • [x] 获取给定对话框中的（未读）邮件列表
  • []马克·夏奈尔已读
  • []按日期和时间检索邮件
  • []下载媒体文件
  • []获取联系人列表
  • []起草一条消息
  • ...

实际使用案例

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

先决条件

安装

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

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

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

配置

电报API配置

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

  1. 从获取API ID和哈希 电报API

  2. 运行以下命令：

    mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>

    输入您从Telegram收到的代码以连接到API。

    如果启用了双因素身份验证，则可能需要密码。

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

Claude桌面配置

配置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的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

    类的属性将用作工具的参数。 类docstring将用作工具描述。

  2. 为新类实现tool_runner函数

    @tool_runner.register
async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]:
    pass

    该函数应返回TextContent、ImageContent或EmbeddedResource的序列。 该函数应该是异步的，并接受新类的单个参数。

  3. 完成！重新启动客户端，新工具应该可用。

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

在终端中调试服务器

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


# List all available tools
uv run cli.py list-tools

# Run the concrete tool
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

在检查器中调试服务器

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

npx @modelcontextprotocol/inspector uv run mcp-telegram

[！警告] 不要忘记在检查器中定义环境变量TELEGRAM_API_ID和TELEGRAM-API_HASH。

故障排除

消息“无法连接到MCP服务器MCP电报”

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

尝试以下操作：

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

相关 MCP