telegram-mcp

一个使用 mtcute 与 Telegram 交互的模型上下文协议 (MCP) 服务器。

功能

• 向聊天发送文本消息

• 在特定聊天中等待传入消息

• 从聊天中读取消息

• 搜索消息

• 列出并获取对话（聊天）信息

• 获取所有聊天中的最近消息

• 为账户和频道设置及查看 emoji 状态 ID

Related MCP server: io.github.daedalus/mcp-telegram-bot

设置

安装

选项 1：下载预构建二进制文件

从 发布页面 下载适用于您平台的最新版本：

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz

• macOS (Intel): telegram-mcp-darwin-x64.tar.gz

• Linux: telegram-mcp-linux-x64.tar.gz

• Windows: telegram-mcp-win-x64.exe.zip

解压归档文件并使二进制文件可执行（Unix 系统）：

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

选项 2：从源码构建

1. 克隆仓库并安装依赖：

   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install

2. 构建可执行文件：

   bun run build

初始设置（仅限首次）

1. 从 https://my.telegram.org 获取您的 Telegram API 凭据

2. 运行初始设置以进行 Telegram 身份验证：

   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp

   服务器将：

   • 提示您输入手机号码

   • 通过 Telegram 向您发送验证码

   • 要求输入验证码

   • 显示绝对存储路径（您在配置 MCP 时需要用到）

3. 记下输出中显示的存储路径。它看起来像这样：

   Storage path: /Users/username/telegram-mcp/bot-data/session

使用方法

作为 MCP 服务器

使用初始设置中的存储路径添加到您的 Claude Desktop 配置中：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

重要：TELEGRAM_STORAGE_PATH 必须是初始设置期间显示的绝对路径。这确保了 MCP 服务器使用已验证的会话。

可用工具

消息工具

• messages_sendText - 向聊天发送文本消息

  • chatId (必填): 聊天/用户 ID 或用户名

  • text (必填): 要发送的消息文本

  • replyToMessageId: 可选，要回复的消息 ID

• messages_getHistory - 获取聊天中的消息历史记录

  • chatId (必填): 聊天/用户 ID 或用户名

  • limit: 消息数量（默认：100，最大：100）

  • offsetId: 用于分页的消息 ID

• messages_search - 搜索消息

  • query (必填): 搜索查询

  • chatId: 要搜索的特定聊天（可选）

  • limit: 结果数量（默认：50）

• messages_getRecent - 获取所有聊天中的最近消息

  • limit: 聊天数量（默认：10）

  • messagesPerChat: 每个聊天的消息数（默认：10）

交互工具

• wait_for_reply - 等待聊天中的下一条消息

  • chatId (必填): 等待消息的聊天/用户 ID 或用户名

  • timeoutSeconds: 超时时间（秒）（默认：60，最大：300）

状态工具

• status_getCurrent - 获取对等方的当前 emoji 状态

  • peerId: 目标对等方，默认为 self

• status_setEmoji - 设置或清除 emoji 状态

  • peerId: 目标对等方，默认为 self

  • emojiId: 自定义 emoji 文档 ID，除非 clear=true，否则必填

  • isCollectible: 当 emojiId 是收藏品 ID 时设置为 true

  • until: 可选的 ISO-8601 时间戳或 Unix 时间戳字符串

  • clear: 清除当前状态而不是设置新状态

• status_listAvailable - 列出可用的默认 emoji 状态 ID

  • scope: self 或 channel（默认：self）

  • limit: 返回的最大 ID 数量（默认：100）

• status_listCollectibles - 列出可用作自身 emoji 状态的已拥有收藏品 ID

  • owner: 要检查的对等方，默认为 self

  • limit: 返回的最大收藏品数量（默认：100）

对话工具

• dialogs_list - 列出所有对话

  • limit: 最大对话数（默认：50）

  • filter: 过滤选项（onlyUsers, onlyGroups, onlyChannels）

• dialogs_getInfo - 获取详细的对话信息

  • chatId (必填): 聊天/用户 ID 或用户名

开发

在开发模式下运行：

bun run dev

服务器将会话数据存储在 bot-data/ 目录中。