Telegram MCP server

Telegram MCP 服务

该服务是 Telegram API 与 AI 助手之间的桥梁，基于 Model Context Protocol。

重要

使用此服务前，请确保已阅读并理解 Telegram API 服务条款。 滥用 Telegram API 可能导致你的账号被暂停。

目录

• 什么是 MCP？
• 此服务有什么功能？
  • 功能
  • 提示词示例
    • 消息管理
    • 整理
    • 沟通
• 安装
  • Homebrew
  • NPX
  • 从发行版本安装
    • MacOS
    • Linux
    • Windows
  • 从源代码安装
• 配置
  • 授权
  • 客户端配置
  • JSON Schema 版本
• Star 历史

什么是 MCP？

Model Context Protocol（MCP）是一种系统，可让 Claude Desktop 或 Cursor 等 AI 应用连接到外部工具和数据源。它为 AI 助手提供了一种清晰、安全的方式来使用本地服务和 API，同时确保用户始终掌握控制权。

此服务有什么功能？

功能

• 获取当前账号信息（tool: tg_me）
• 列出对话，可选按未读状态筛选（tool: tg_dialogs）
• 将对话标记为已读（tool: tg_read）
• 获取指定对话中的消息（tool: tg_dialog）
• 向任意对话发送草稿消息（tool: tg_send）

提示词示例

以下是一些可与 AI 助手搭配使用的提示词示例：

消息管理

• “查看我的 Telegram 中是否有重要的未读消息”
• “总结我所有未读的 Telegram 消息”
• “阅读并分析我的未读消息，并在需要时准备回复草稿”
• “查看非重要的未读消息，并向我简要概述”

整理

• “分析我的 Telegram 对话，并建议一种文件夹结构”
• “帮我按重要程度对 Telegram 聊天进行分类”
• “找出所有与工作相关的对话，并建议如何整理”

沟通

• “监控特定聊天中有关 [topic] 的动态”
• “为 [chat] 中的最后一条消息拟一份礼貌的回复”
• “检查我的聊天中是否有尚未回答的问题”

安装

Homebrew

你可以使用 brew 在 macOS/Linux 上安装二进制发行版：

# Install
brew install chaindead/tap/telegram-mcp

# Update
brew upgrade chaindead/tap/telegram-mcp

NPX

你可以使用 npx 直接运行最新版本（支持 macOS、Linux 和 Windows）：

npx -y @chaindead/telegram-mcp

使用 NPX 时，请按如下方式修改标准命令和配置：

• 授权命令改为：

npx -y @chaindead/telegram-mcp auth ...

• Claude MCP 服务配置改为：

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@chaindead/telegram-mcp"],
      "env": {
        "TG_APP_ID": "<your-api-id>",
        "TG_API_HASH": "<your-api-hash>"
      }
    }
  }
}

完整的设置说明请参阅授权和客户端配置。

从发行版本安装

MacOS

# For Intel Mac (x86_64)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_x86_64.tar.gz

# For Apple Silicon (M1/M2)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_arm64.tar.gz

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

Linux

# For x86_64 (64-bit)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_x86_64.tar.gz

# For ARM64
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_arm64.tar.gz

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

Windows

从源代码安装

要求：

• Go 1.24 或更高版本
• GOBIN 位于 PATH 中

go install github.com/chaindead/telegram-mcp@latest

配置

授权

使用该服务前，你需要连接到 Telegram API。

1. 从 Telegram API 获取 API ID 和哈希值

2. 运行以下命令：

   注意： 如果启用了 2FA：添加 --password <2fa_password>

   注意： 如果要覆盖现有会话：添加 --new

   telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>
   

   📩 输入你从 Telegram 收到的验证码，以连接到 API。

3. 完成！请给此项目点个 ⭐️，支持项目开发。

客户端配置

以下示例介绍如何配置 Claude Desktop，使其识别 Telegram 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. 添加服务配置

   Claude Desktop 配置：

    {
      "mcpServers": {
        "telegram": {
          "command": "telegram-mcp",
          "env": {
            "TG_APP_ID": "<your-app-id>",
            "TG_API_HASH": "<your-api-hash>",
            "PATH": "<path_to_telegram-mcp_binary_dir>",
            "HOME": "<path_to_your_home_directory"
          }
        }
      }
    }
   

   Cursor 配置：

   {
     "mcpServers": {
       "telegram-mcp": {
         "command": "telegram-mcp",
         "env": {
           "TG_APP_ID": "<your-app-id>",
           "TG_API_HASH": "<your-api-hash>"
         }
       }
     }
   }
   

JSON Schema 版本

某些 MCP 客户端（例如 VS Code）不支持 JSON Schema Draft 2020-12，会拒绝使用该版本的工具。你可以通过设置 --schema-version 标志或 TG_SCHEMA_VERSION 环境变量来覆盖 JSON Schema 版本。

常用值：

Star 历史