MTM - MCP Telegram MORE

Claude Code를 위한 맞춤형 텔레그램 채널 — 텔레그램 봇을 Claude 세션을 위한 모든 기능을 갖춘 원격 제어기로 바꿔주는 데몬 + MCP 서버 + MiniApp입니다.

주요 기능

Claude와 원격 채팅

• 모든 텔레그램 클라이언트에서 Claude에게 메시지를 보낼 수 있으며, Claude의 응답도 동일한 방식으로 스트리밍됩니다.

• 양방향 파일 첨부(업로드/스크린샷/다운로드)를 지원합니다.

• 봇 내부의 MiniApp은 채팅, 작업, 상태의 세 가지 탭을 제공합니다.

텔레그램을 통한 도구 승인

• 모든 위험한 도구 호출(Bash, Edit, Write, MCP 도구 등)에 대해 명시적인 승인을 요구할 수 있습니다.

• 승인 요청은 허용/거부 버튼이 포함된 텔레그램 메시지로 도착하며, 휴대폰에서 바로 승인할 수 있습니다.

• 도구 수준의 허용 목록을 통해 안전한 도구는 자동 승인할 수 있습니다 (/allow Read, /deny Bash sudo).

• 전역 YOLO 모드 (/yolo on)를 사용하면 일시적으로 승인 절차를 비활성화할 수 있습니다.

실시간 작업 추적

• Claude의 TodoWrite 목록이 작업 탭에 실시간으로 미러링됩니다.

• 상태 전환(대기 중 → 진행 중 → 완료됨)이 WebSocket을 통해 실시간으로 업데이트됩니다.

하위 에이전트 및 도구 가시성

• MiniApp 상단의 고정 상태 표시줄은 Claude가 현재 무엇을 하고 있는지 보여줍니다 ("main: Edit · config.ts", "main + 2 subagents running").

• 각 하위 에이전트 생성에 대한 접기 가능한 에이전트 버블 — 각 하위 에이전트가 실행한 도구를 자세히 살펴볼 수 있습니다.

• 중요한 도구(쓰기 작업, Task, MCP)는 강조 표시되며, 읽기 전용 도구는 기본적으로 접혀 있습니다.

• 도구 이벤트 기록은 기본적으로 7일간 보관됩니다(설정 가능).

워크스페이스 인식

• 서로 다른 프로젝트에서 여러 Claude 세션을 동시에 실행할 수 있으며, 각 세션은 고유한 워크스페이스에 매핑됩니다.

• 봇의 /ws 명령어를 사용하여 들어오는 메시지의 대상 워크스페이스를 전환할 수 있습니다.

접근 제어

• 페어링 절차: 봇에게 DM 전송 → 6자리 코드 수신 → /mcp-telegram:access pair <code>로 인증.

• owner/user 역할이 있는 허용 목록; owner는 권한을 부여하거나 제거할 수 있습니다.

• 정책 모드: pairing(코드 전용), allowlist(비공개), open(누구나 접근 가능 — 개발용).

터널 추상화

• 플러그인 가능한 터널 제공자를 통해 공용 URL을 노출합니다.

• 기본 URL은 봇의 MiniApp 버튼으로 텔레그램에 자동 푸시되며, 허용 목록에 있는 모든 사용자에 대해 채팅별 재정의를 지원합니다.

Related MCP server: Straight Connect

사전 요구 사항

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

• 선택한 제공자에 맞는 터널 도구:

  • cloudflared — 설치 (기본값)

  • tuna — 설치 (대안)

  • 또는 manual 모드를 통해 직접 URL 사용

• @BotFather에서 발급받은 텔레그램 봇 토큰 (/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이 텔레그램 봇으로 자동 푸시됩니다(기본 MiniApp 버튼 및 허용된 사용자의 채팅별 재정의 모두 포함).

슬래시 명령어 (Claude Code 내)

모든 스킬은 ~/.mcp-tg/admin.token(첫 실행 시 자동 생성, 모드 0600)에 있는 베어러 토큰을 사용하여 http://127.0.0.1:17080/admin/*에서 실행 중인 데몬과 통신합니다.

봇 명령어 (텔레그램 내)

대역 외: 명령어가 아닌 텍스트를 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) — 한 번 빌드되어 데몬이 터널 URL에서 정적으로 제공하는 React SPA입니다.

• 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 스킬은 메시지를 통한 프롬프트 주입을 방지하기 위해 텔레그램 입력 이후의 작업을 거부합니다.

• MiniApp initData는 서버 측에서 검증됩니다(텔레그램 사양에 따른 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 인덱스는 압축된 감사 추적으로 무기한 보관됩니다.