MTM - MCP Telegram MORE

Claude Code用のカスタムTelegramチャンネル — TelegramボットをClaudeセッションのフル機能リモートコントロールに変えるデーモン + MCPサーバー + MiniAppです。

機能

Claudeとのリモートチャット

• 任意のTelegramクライアントからClaudeにメッセージを送信でき、Claudeの返信も同様にストリーミングで戻ってきます。

• 双方向のファイル添付（アップロード / スクリーンショット / ダウンロード）をサポート。

• ボット内のMiniAppには、チャット、タスク、ステータスの3つのタブがあります。

Telegram経由のツール承認

• リスクのあるツール呼び出し（Bash、Edit、Write、MCPツールなど）は、明示的な承認を必須にできます。

• 承認プロンプトは「許可/拒否」ボタン付きのTelegramメッセージとして届くため、スマートフォンから承認可能です。

• ツールレベルの許可リストにより、安全なツールを自動承認できます（/allow Read、/deny Bash sudo）。

• グローバルなYOLOモード（/yolo on）で、一時的に承認を無効化できます。

ライブタスク追跡

• Claudeの TodoWrite リストが、タスクタブにリアルタイムでミラーリングされます。

• ステータスの遷移（保留中 → 進行中 → 完了）がWebSocket経由でライブ更新されます。

サブエージェントとツールの可視性

• MiniApp上部の固定ステータスバーで、Claudeの現在の動作状況を表示します（「main: Edit · config.ts」、「main + 2つのサブエージェントが実行中」など）。

• サブエージェントごとに折りたたみ可能なエージェントバブルを表示 — 各サブエージェントが実行したツールを詳細に確認できます。

• 重要なツール（書き込みアクション、Task、MCP）は強調表示され、読み取り専用ツールはデフォルトで折りたたまれます。

• ツールイベント履歴はデフォルトで7日間保持されます（設定可能）。

ワークスペース認識

• 異なるプロジェクト間で複数のClaudeセッションを同時に実行でき、それぞれが独自のワークスペースにマッピングされます。

• ボット内の /ws コマンドで、受信メッセージのターゲットとなるワークスペースを切り替えられます。

アクセス制御

• ペアリングフロー：ボットにDM送信 → 6桁のコードを受信 → /mcp-telegram:access pair <code> で認証。

• owner/user ロールを持つ許可リスト。owner は昇格や削除が可能です。

• ポリシーモード：pairing（コードのみ）、allowlist（クローズド）、open（誰でも — 開発用のみ）。

トンネル抽象化

• プラグイン可能なトンネルプロバイダー経由でパブリックURLを公開。

• デフォルトのURLは、ボットのMiniAppボタンとしてTelegramに自動プッシュされます（許可リストユーザーごとのチャット別オーバーライドを含む）。

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 から読み込まれます。シェルでエクスポートすることも可能です。

~/.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 — ワークスペースが接続される前にシステムイベントをブロードキャストするために使用されるオプションの識別子。

トンネルプロバイダーの選択

# 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）にあるベアラートークンを使用して、実行中のデーモン http://127.0.0.1:17080/admin/* と通信します。

ボットコマンド (Telegram内)

帯域外：コマンド以外のテキストをDMで送信すると、現在選択されているワークスペースの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)

セキュリティ

• ペアリングコードはメモリ内のみに存在します。デーモンを再起動すると無効になるため、新しいコードが必要な場合はボットにDMしてください。

• ボット自体を通じて届いたペアリングリクエストは決して承認しないでください。/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 インデックスは、コンパクトな監査証跡として無期限に保持されます。