MTM - MCP Telegram MORE

Custom Telegram channel for Claude Code — a daemon + MCP server + MiniApp that turns a Telegram bot into a full-featured remote control for your Claude sessions.

Features

Remote chat with Claude

• Send messages to Claude from any Telegram client; Claude's replies stream back the same way.
• File attachments supported in both directions (uploads / screenshots / downloads).
• MiniApp inside the bot with three tabs: Chat, Tasks, Status.

Tool approvals over Telegram

• Every risky tool call (Bash, Edit, Write, MCP tools, etc.) can require explicit approval.
• Approval prompts arrive as Telegram messages with Allow/Deny buttons; you approve from your phone.
• Tool-level allowlist lets you auto-approve safe tools (/allow Read, /deny Bash sudo).
• Global YOLO mode (/yolo on) temporarily disables approvals.

Live task tracking

• Claude's TodoWrite list is mirrored to the Tasks tab in real-time.
• Status transitions (pending → in_progress → completed) update live over WebSocket.

Sub-agent & tool visibility

• Sticky status bar at the top of the MiniApp shows what Claude is doing right now ("main: Edit · config.ts", "main + 2 subagents running").
• Collapsible agent bubbles for each sub-agent spawn — drill down into the tools each sub-agent ran.
• Important tools (write-actions, Task, MCP) are highlighted; read-only tools collapsed by default.
• Tool-event history retained for 7 days by default (configurable).

Workspace awareness

• Multiple concurrent Claude sessions across different projects, each mapped to its own workspace.
• /ws command in the bot switches which workspace incoming messages target.

Access control

• Pairing flow: DM the bot → receive 6-digit code → redeem with /mcp-telegram:access pair <code>.
• Allowlist with owner/user roles; owner can promote and remove.
• Policy modes: pairing (code-only), allowlist (closed), open (anyone — only for dev).

Tunnel abstraction

• Public URL exposed via a pluggable tunnel provider.
• Default URL is auto-pushed to Telegram as the bot's MiniApp button, including per-chat overrides for every allowlisted user.

---

Prerequisites

• Bun — curl -fsSL https://bun.sh/install | bash
• A tunnel tool matching your chosen provider:
  • cloudflared — install (default)
  • tuna — install (alt)
  • Or bring your own URL via manual mode
• A Telegram bot token from @BotFather (use /newbot).
• Node.js (for the Claude Code hook scripts — any recent version).

---

Quick start

# 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.

---

Configuration

~/.mcp-tg/.env (required)

Variable	Default	Purpose
TELEGRAM_BOT_TOKEN	— (required)	Bot token from @BotFather.
MCP_TG_PORT	17080	Local port the daemon listens on.
MCP_TG_DATA_DIR	~/.mcp-tg	Where the DB, uploads, lock, tokens live.
MCP_TG_JWT_SECRET	auto-gen	HS256 signing key for MiniApp sessions. Generate on first boot if absent.
MCP_TG_HOOK_TOKEN	auto-gen via /configure	Shared secret used by Claude Code hooks to POST into daemon.
MCP_TG_DAEMON_PORT	17080	Port the hook scripts target (usually same as MCP_TG_PORT).
MCP_TG_TOOL_EVENTS_TTL_DAYS	7	Retention for the tool-events audit log (hourly cleanup).

Variables are read from ~/.mcp-tg/.env by the daemon at startup; you can also export them in your shell.

~/.mcp-tg/config.json (daemon-managed)

Managed by the daemon and the /mcp-telegram:configure skill. Keys:

• tunnel_provider — one of cloudflared | tuna | manual | none.
• tunnel_manual_url — only used when tunnel_provider = manual; must be a publicly reachable HTTPS URL proxying to 127.0.0.1:17080.
• default_workspace — optional slug used for system-event broadcasts before any workspace connects.

Choosing a tunnel provider

# 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

After changing provider, restart the daemon. The new URL is pushed to the Telegram bot automatically — both as the default MiniApp button and for every allowlisted user's per-chat override.

---

Slash commands (in Claude Code)

Command	Description
/mcp-telegram:configure <TOKEN>	Write bot token to ~/.mcp-tg/.env.
/mcp-telegram:configure tunnel <provider>	Set tunnel provider (see above).
/mcp-telegram:access pair <CODE>	Redeem a 6-digit pair code received via bot DM.
/mcp-telegram:access list	Show the current allowlist.
/mcp-telegram:access remove <userId>	Revoke access for a user.
/mcp-telegram:access policy [<mode>]	Show or set pairing / allowlist / open.
/mcp-telegram:install-service	Install a systemd --user service so the daemon starts on login (Linux only).

All skills talk to the running daemon at http://127.0.0.1:17080/admin/* using the bearer token in ~/.mcp-tg/admin.token (auto-generated on first boot, mode 0600).

Bot commands (in Telegram)

Command	Description
/ws	List workspaces / switch the target for incoming messages.
/approvals	Show current approval status / toggle on/off.
/allowlist	Manage the auto-approve tool allowlist.
/allow <tool> [substring]	Add an allow rule.
/deny <tool> [substring]	Add a deny rule.
/yolo on | off	Globally disable/enable approval prompts.

Out-of-band: DM any non-command text to send it to the currently selected workspace's Claude session.

---

Deployment

For ad-hoc use, bun run --cwd packages/daemon start in a terminal is enough. For anything persistent:

# 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

On macOS / Windows run the daemon under your own process manager (launchd, pm2, nssm, etc.) — the MVP does not ship install scripts for those platforms.

---

Architecture (brief)

• daemon (packages/daemon) — the only long-running process. Owns the bot, HTTP + WS servers, SQLite, tunnel, and approvals state.
• mcp-server (packages/mcp-server) — a stdio process spawned per Claude Code session; thin WebSocket client of the daemon.
• miniapp (packages/miniapp) — React SPA built once, served statically by the daemon at the tunnel URL.
• shared (packages/shared) — protocol, status, and tool-event types.
• plugin (plugin/) — Claude Code plugin with MCP server config, approval hooks, TodoWrite sync hook, and the sub-agent tool-events hook.

Full design docs live under docs/superpowers/specs/.

---

Tests

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

---

Security

• Pairing codes are in-memory only — a daemon restart invalidates them; DM the bot for a fresh code.
• Never approve a pairing request that arrived through the bot itself. The /mcp-telegram:access skill refuses operations downstream of Telegram input to prevent prompt-injection via messages.
• MiniApp initData is validated server-side (HMAC-SHA256 per Telegram spec). MiniApp JWTs live 15 min.
• Daemon binds to 127.0.0.1; public reach exists only through the tunnel provider.
• MCP_TG_HOOK_TOKEN is the only credential required by hooks; it stays inside ~/.mcp-tg/.env (mode 0600) and is never sent outside 127.0.0.1.
• Tool-event history is pruned after MCP_TG_TOOL_EVENTS_TTL_DAYS (default 7); agent_sessions index is kept indefinitely as a compact audit trail.