claude-ops-telegram-server

claude-ops Telegram MCP 服务

用于 /ops:ops-inbox 技能的用户身份验证 Telegram MCP 服务。它通过 MTProto（gram.js）以个人 Telegram 账号进行身份验证，而非使用 BotFather 机器人，因此可以读取和回复真实的私信对话。

为什么使用用户身份验证，而不是机器人？

机器人无法读取两个用户之间私人聊天中发送的消息，只能读取直接发送给机器人的消息。对于 /ops:ops-inbox 用例（管理所有者的个人收件箱），我们必须以用户账号进行身份验证。

设置

1. 获取 API 凭据

前往 https://my.telegram.org/apps 并创建一个个人应用（不是机器人）。你将获得：

• api_id（整数）
• api_hash（32 个字符的字符串）

2. 安装依赖项

cd claude-ops/telegram-server
npm install

3. 首次运行身份验证（交互式）

TELEGRAM_API_ID=12345 \
TELEGRAM_API_HASH=abcdef... \
TELEGRAM_PHONE=+15551234567 \
node index.js --auth

脚本会提示你输入短信验证码，以及（如果已启用）你的 2FA 密码。成功后，它会输出一个 TELEGRAM_SESSION 字符串——请妥善保存（这是你的会话令牌）。

4. 在 Claude Code 中配置 MCP 服务

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/claude-ops/telegram-server/index.js"],
      "env": {
        "TELEGRAM_API_ID": "${TELEGRAM_API_ID}",
        "TELEGRAM_API_HASH": "${TELEGRAM_API_HASH}",
        "TELEGRAM_SESSION": "${TELEGRAM_SESSION}",
        "TELEGRAM_PHONE": "${TELEGRAM_PHONE}"
      }
    }
  }
}

从密钥管理器（Doppler、1Password、direnv）导出环境变量——绝不要提交：

export TELEGRAM_API_ID="..."
export TELEGRAM_API_HASH="..."
export TELEGRAM_SESSION="..."   # from step 3
export TELEGRAM_PHONE="+1..."
export TELEGRAM_ENABLED=true    # enables in ops-unread detection

重启 Claude Code 以加载 MCP 服务。

工具

工具	描述
list_dialogs	列出最近的对话（私信、群组、频道）及未读数量
get_messages	获取特定聊天中的消息
send_message	向聊天或用户发送消息
search_messages	在所有对话中进行全文搜索

安全

• 绝不要提交 TELEGRAM_SESSION——它等同于你的密码
• 会话令牌与设备绑定；如果令牌被盗，请通过 Telegram 应用 → 设置 → 设备退出登录
• 所有凭据均来自环境变量；此仓库中没有硬编码任何内容
• 服务通过 stdio 运行（仅限本地）；除 Telegram 官方 API 外，不会暴露到网络

故障排除

“会话已失效”：重新运行 node index.js --auth 以生成新的会话。

“TELEGRAM_API_ID is required”：环境变量未传递给 MCP 服务。请检查 ~/.claude/settings.json 中的 env 配置块。

速率限制：Telegram 会对每个账号实施限制。如果触发限制，请等待 15–30 分钟后再试。