Claude Telegram Bridge

克劳德电报桥

一个MCP服务器，当您离开终端时，Claude Code可以通过Telegram与您通信。在自主工作会议期间，Claude会向您的手机发送问题和进度更新，并收到您的回复。

支持多个并发的Claude会话——每条消息都是线程化的，因此您的回复会自动路由到正确的会话。

运作原理

You (Telegram)    Telegram Bot API    MCP Server    Claude Code

1. 你告诉克劳德你要离开（或派 /away 来自Telegram）
2. 克劳德激活远程模式，并通过Telegram路由通信
3. Claude将任务摘要和问题发送到您的Telegram聊天室
4. 你 滑动回复 到特定消息--回复路由到正确的会话
5. 当你回来时，在终端上说出来或发送 /back 来自Telegram

并发会话

当运行多个Claude Code实例时（例如，一个在前端工作，另一个在后端工作），每个会话的消息都会获得唯一的ID。为了回复正确的会话， 滑动回复特定消息 在Telegram上。这是Telegram的原生用户体验，不需要前缀或会话ID。

无线程消息（在不回复特定消息的情况下发送）将转到下一个检查的会话。

先决条件

• Python 3.11+
• 紫外线 包管理器
• Telegram机器人代币（来自 @植物学家)
• 您的Telegram聊天ID

设置

1.创建Telegram Bot

1. 打开电报和消息 @植物学家
2. 发送 /newbot 并按照提示进行操作
3. 复制您收到的机器人令牌

2.克隆和安装

git clone https://github.com/RicardoAGL/claude-telegram-bridge.git
cd claude-telegram-bridge
uv sync

3.配置环境

创建一个 .envrc 项目根目录中的文件：

export TELEGRAM_BOT_TOKEN="your-bot-token-here"
export TELEGRAM_CHAT_ID="your-chat-id-here"

要查找您的聊天ID，请在Telegram上向您的机器人发送任何消息，然后运行：

source .envrc
uv run python setup_check.py

这将打印您的机器人信息和最近的聊天ID。

4.注册MCP服务器

添加到您的Claude Code MCP配置中(~/.claude.json):

{
  "mcpServers": {
    "telegram-bridge": {
      "command": "/bin/bash",
      "args": ["-c", "source /path/to/claude-telegram-bridge/.envrc && uv run --directory /path/to/claude-telegram-bridge claude-telegram-bridge"]
    }
  }
}

5.允许使用工具（可选）

若要在不提示的情况下自动批准工具，请将其添加到您的 ~/.claude/settings.json 允许列表：

{
  "permissions": {
    "allow": [
      "mcp__telegram-bridge__setup_check",
      "mcp__telegram-bridge__set_away_mode",
      "mcp__telegram-bridge__send_question",
      "mcp__telegram-bridge__send_summary",
      "mcp__telegram-bridge__check_messages"
    ]
  }
}

6.验证

启动一个新的Claude Code会话，并要求Claude运行 setup_check。它应该显示您的机器人名称和聊天ID。

用法

从终端（克劳德代码）

告诉克劳德你要离开了：

“我要去AFK，激活离开模式”

克劳德将激活离开模式，并开始通过Telegram路由。当你回来时：

“我回来了”

Claude关闭离开模式并切换回终端通信。

来自Telegram（远程控制）

将这些命令直接发送到您的机器人：

这使您无需触摸终端即可切换手机的模式。下次克劳德打电话来 check_messages，它接收命令。

MCP工具

消息处理

网桥的设计使您即使在多个会话中也不会丢失消息：

• 回复线程 --每个问题/摘要都会获得一个唯一的Telegram消息ID。滑动对特定消息的回复，将您的答案发送到正确的Claude会话。
• 等待答复 --如果一个会话收到了针对另一个会话的回复，则会将其存储在共享状态文件中。目标会话在下一次轮询中找到它。
• 多消息回复 --在第一个回复到达之后， send_question 额外轮询3秒，以收集快速连续发送的后续消息。
• 发送后投票 — send_summary 在发送后进行长达30秒的投票，以获取您的即时回复。
• 消息缓冲区 --无线程消息在状态中缓冲。下一个 check_messages 调用会耗尽缓冲区。

建筑

• 回复线程 --使用Telegram的本地 reply_to_message 字段将回复路由到正确的会话。没有会话ID或面向用户的前缀。
• 共享状态文件 — ~/.claude/telegram-bridge-state.json 在并发MCP实例之间共享。包含离开模式、更新偏移、消息缓冲区和待处理回复。
• 长轮询 --使用Telegram的 getUpdates 服务器端超时。不需要webhook基础架构。
• 命令处理 — check_messages 始终处理 /away, /back, /status 无论离开模式状态如何，都可以使用命令进行远程激活。
• 纯文本 --消息使用纯文本（无Markdown）来避免解析项目名称或摘要中的特殊字符问题。

发展

# Install all dependencies (including dev tools)
uv sync

# Run checks (same as CI)
uv run ruff check src/        # Lint
uv run ruff format --check src/ # Format check
uv run pyright src/            # Type check

CI/CD

GitHub Actions在每次推送时运行 main 关于PR：

• 绒毛和格式检查（褶皱）
• 类型检查（版权）
• 进口验证
• 针对Python 3.11、3.12和3.13进行了测试

许可证

麻省理工学院