MTM - MCP Telegram MORE

用于 Claude Code 的自定义 Telegram 频道 —— 一个守护进程 + MCP 服务器 + MiniApp，将 Telegram 机器人变成 Claude 会话的全功能远程控制器。

功能特性

与 Claude 远程聊天

• 从任何 Telegram 客户端向 Claude 发送消息；Claude 的回复会以同样的方式流式传输回来。

• 支持双向文件附件（上传/截图/下载）。

• 机器人内置 MiniApp，包含三个选项卡：聊天 (Chat)、任务 (Tasks)、状态 (Status)。

通过 Telegram 进行工具审批

• 每一个高风险的工具调用（Bash、Edit、Write、MCP 工具等）都可以要求明确的审批。

• 审批提示以 Telegram 消息形式发送，带有“允许/拒绝”按钮；您可以直接在手机上进行审批。

• 工具级允许列表允许您自动批准安全工具（/allow Read，/deny Bash sudo）。

• 全局 YOLO 模式 (/yolo on) 可暂时禁用审批。

实时任务跟踪

• Claude 的 TodoWrite 列表会实时镜像到“任务”选项卡中。

• 状态转换（pending → in_progress → completed）通过 WebSocket 实时更新。

子代理与工具可见性

• MiniApp 顶部的粘性状态栏显示 Claude 当前正在执行的操作（例如：“main: Edit · config.ts”，“main + 2 个子代理正在运行”）。

• 每个子代理生成的可折叠代理气泡 —— 可深入查看每个子代理运行的工具。

• 重要工具（写入操作、Task、MCP）会被高亮显示；只读工具默认折叠。

• 工具事件历史记录默认保留 7 天（可配置）。

工作区感知

• 支持跨不同项目的多个并发 Claude 会话，每个会话映射到其自己的工作区。

• 机器人中的 /ws 命令可切换传入消息的目标工作区。

访问控制

• 配对流程：私聊机器人 → 获取 6 位代码 → 使用 /mcp-telegram:access pair <code> 进行兑换。

• 带有 owner（所有者）/user（用户）角色的允许列表；owner 可以进行提升权限和移除操作。

• 策略模式：pairing（仅限代码）、allowlist（封闭）、open（任何人 —— 仅供开发使用）。

隧道抽象

• 通过可插拔的隧道提供商暴露公共 URL。

• 默认 URL 会自动推送到 Telegram 作为机器人的 MiniApp 按钮，包括针对每个已加入允许列表用户的按聊天覆盖设置。

Related MCP server: Straight Connect

先决条件

• Bun — curl -fsSL https://bun.sh/install | bash

• 与您选择的提供商匹配的隧道工具：

  • cloudflared — 安装（默认）

  • tuna — 安装（备选）

  • 或者通过 manual 模式使用您自己的 URL

• 来自 @BotFather 的 Telegram 机器人令牌（使用 /newbot）。

• Node.js（用于 Claude Code 钩子脚本 —— 任何较新版本）。

快速开始

# 1. Clone & install workspace deps
git clone <repo> mcp-telegram && cd mcp-telegram
bun install

# 2. Put the bot token into the daemon's env file
mkdir -p ~/.mcp-tg
echo "TELEGRAM_BOT_TOKEN=<your-bot-token>" > ~/.mcp-tg/.env

# 3. Build the MiniApp (served statically by the daemon)
bun run --cwd packages/miniapp build

# 4. Start the daemon (long-running; keep in a terminal or use install-service)
bun run --cwd packages/daemon start
# Logs print the public tunnel URL and port 17080.

# 5. Load the plugin into Claude Code (for hook + MCP integration)
claude --dangerously-load-development-channels plugin:mcp-telegram@mcp-telegram-local

# 6. From inside Claude Code, configure and pair
/mcp-telegram:configure <BOT_TOKEN>
# DM your bot in Telegram → receive a 6-digit pair code
/mcp-telegram:access pair ABC123

# 7. Open the MiniApp by tapping the "Open" button in the bot chat.

配置

~/.mcp-tg/.env (必需)

变量在守护进程启动时从 ~/.mcp-tg/.env 读取；您也可以在 shell 中导出它们。

~/.mcp-tg/config.json (守护进程管理)

由守护进程和 /mcp-telegram:configure 技能管理。键值：

• tunnel_provider — cloudflared | tuna | manual | none 之一。

• tunnel_manual_url — 仅在 tunnel_provider = manual 时使用；必须是代理到 127.0.0.1:17080 的公共可访问 HTTPS URL。

• default_workspace — 在任何工作区连接之前用于系统事件广播的可选 slug。

选择隧道提供商

# Default: cloudflared (auto-generated trycloudflare URL, rotates per restart)
/mcp-telegram:configure tunnel cloudflared

# tuna.am alternative
/mcp-telegram:configure tunnel tuna

# Bring-your-own public URL (nginx, frp, your domain, etc.)
/mcp-telegram:configure tunnel manual
# then edit ~/.mcp-tg/config.json and set tunnel_manual_url to your HTTPS endpoint.

# No public access (local MiniApp only; Telegram bot still works for chat)
/mcp-telegram:configure tunnel none

更改提供商后，请重启守护进程。新 URL 会自动推送到 Telegram 机器人 —— 同时作为默认的 MiniApp 按钮，以及针对每个已加入允许列表用户的按聊天覆盖设置。

斜杠命令 (在 Claude Code 中)

所有技能都使用 ~/.mcp-tg/admin.token（首次启动时自动生成，模式 0600）中的 bearer 令牌与运行中的守护进程 http://127.0.0.1:17080/admin/* 进行通信。

机器人命令 (在 Telegram 中)

带外操作：私聊发送任何非命令文本，即可将其发送到当前选定工作区的 Claude 会话。

部署

对于临时使用，在终端中运行 bun run --cwd packages/daemon start 即可。对于任何持久化需求：

# Linux — systemd user service (starts at login, restarts on failure)
/mcp-telegram:install-service

# Logs: journalctl --user -u mcp-telegram -f
# Stop: systemctl --user stop mcp-telegram
# Disable: systemctl --user disable mcp-telegram

在 macOS / Windows 上，请在您自己的进程管理器（launchd、pm2、nssm 等）下运行守护进程 —— MVP 版本未提供针对这些平台的安装脚本。

架构 (简述)

• daemon (packages/daemon) — 唯一的长驻进程。拥有机器人、HTTP + WS 服务器、SQLite、隧道和审批状态。

• mcp-server (packages/mcp-server) — 每个 Claude Code 会话生成的 stdio 进程；守护进程的轻量级 WebSocket 客户端。

• miniapp (packages/miniapp) — React SPA，构建一次，由守护进程在隧道 URL 处静态提供。

• shared (packages/shared) — 协议、状态和工具事件类型。

• plugin (plugin/) — 带有 MCP 服务器配置、审批钩子、TodoWrite 同步钩子和子代理工具事件钩子的 Claude Code 插件。

完整的设计文档位于 docs/superpowers/specs/ 下。

测试

bun test                          # all workspaces
bun test --cwd packages/daemon    # daemon-only
bun test --cwd packages/miniapp   # MiniApp (vitest)

安全性

• 配对码仅存在于内存中 —— 守护进程重启会使其失效；私聊机器人获取新代码。

• 永远不要批准通过机器人本身发起的配对请求。/mcp-telegram:access 技能会拒绝 Telegram 输入下游的操作，以防止通过消息进行提示词注入。

• MiniApp initData 在服务器端进行验证（根据 Telegram 规范使用 HMAC-SHA256）。MiniApp JWT 的有效期为 15 分钟。

• 守护进程绑定到 127.0.0.1；公共访问仅通过隧道提供商实现。

• MCP_TG_HOOK_TOKEN 是钩子所需的唯一凭据；它保留在 ~/.mcp-tg/.env (模式 0600) 中，且永远不会发送到 127.0.0.1 之外。

• 工具事件历史记录在 MCP_TG_TOOL_EVENTS_TTL_DAYS（默认 7 天）后被修剪；agent_sessions 索引作为紧凑的审计跟踪被永久保留。