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.