Telegram 알림 MCP 서버

Claude Code가 작업을 완료하면 Telegram으로 알림을 보내는 MCP(Model Context Protocol) 서버입니다. Cloudflare Agents SDK를 사용하여 TypeScript로 구축되었으며 Cloudflare Workers에 배포할 수 있습니다.

📢 Discord를 선호하시나요? Discord 알림이 필요하다면 Discord Notification MCP를 확인해 보세요.

기능

• 🤖 MCP 도구: 알림을 보내기 위한 send_telegram_message 도구 제공

• 🚀 Cloudflare Workers: 전 세계에 분산된 서버리스 실행

• 🔐 인증: Cloudflare 시크릿으로 저장된 bearer 토큰 필요

• 🌐 Streamable HTTP: 최신 무상태 MCP 전송 방식 사용

• 💬 메시지 포맷팅: Markdown 및 HTML 포맷팅 지원

• 📝 포맷팅: Markdown 및 HTML 메시지 포맷팅 지원

Related MCP server: mcp-telegram-claudecode

아키텍처

이 서버는 Cloudflare의 Agents SDK를 사용하여 MCP 사양을 구현합니다:

• POST /mcp: MCP 통신을 위한 무상태 Streamable HTTP 엔드포인트

• GET /sse: 410 Gone 반환; 레거시 SSE 클라이언트는 /mcp로 마이그레이션해야 함

• TypeScript, MCP SDK, Cloudflare Agents SDK로 구축

• 적절한 JSON-RPC 2.0 오류 처리

• Node.js 호환 모드 활성화

설정

사전 요구 사항

1. Telegram 봇: @BotFather를 통해 봇을 만들고 봇 토큰을 받으세요

2. 채팅 ID: 봇에게 메시지를 보낸 후 다음을 방문하여 채팅 ID를 확인하세요:

   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

3. Cloudflare 계정: cloudflare.com에서 가입하세요

설치

1. 이 저장소를 클론하세요

2. 의존성을 설치하세요:

   pnpm install

구성

1. 예제 파일에서 .dev.vars 파일을 만드세요:

   cp .dev.vars.example .dev.vars

   그런 다음 .dev.vars에 봇 토큰과 채팅 ID를 입력하세요. 이 파일은 로컬 개발과 배포 모두에 사용됩니다.

2. 프로덕션 배포를 위해 MCP bearer 토큰을 생성하고 Cloudflare 시크릿을 설정하세요:

   openssl rand -hex 32
   pnpm exec wrangler secret put BOT_TOKEN
   pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional
   pnpm exec wrangler secret put MCP_AUTH_TOKEN

   참고: DEFAULT_CHAT_ID는 선택 사항입니다. 설정하지 않은 경우 send_telegram_message 도구를 호출할 때 chat_id 매개변수를 제공해야 합니다.

3. 원하는 경우 wrangler.toml의 worker 이름을 업데이트하세요

배포

Cloudflare Workers에 배포:

Wrangler를 사용하여 배포:

# First set secrets
pnpm exec wrangler secret put BOT_TOKEN
pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional

# Then deploy
pnpm run deploy

대안: 지속적 배포(Continuous Deployment)

Cloudflare 대시보드에서 직접 지속적 배포를 설정할 수도 있습니다. Cloudflare와 Git 통합에 대해 자세히 알아보세요.

Claude Code 구성

Streamable HTTP와 동일한 bearer 토큰을 사용하여 MCP 서버를 Claude Code에 추가하세요:

# For production deployment
claude mcp add --scope user --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify https://your-worker-name.workers.dev/mcp

# For local development
claude mcp add --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify http://localhost:8787/mcp

토큰은 Telegram 봇 토큰이 아닌 MCP 엔드포인트에 대한 클라이언트 액세스입니다. 봇 토큰을 Claude의 MCP 구성에 절대 넣지 마세요.

다음으로 구성을 확인할 수 있습니다:

claude mcp list

사용법

구성이 완료되면 Claude Code는 필요할 때마다 Telegram으로 알림을 보낼 수 있습니다.

사용 가능한 도구

send_telegram_message: Telegram으로 알림 메시지 보내기

• text (필수): 보낼 메시지 텍스트

• chat_id (선택): Telegram 채팅 ID (제공되지 않은 경우 DEFAULT_CHAT_ID 사용)

• parse_mode (선택): 메시지 포맷팅을 위한 "Markdown" 또는 "HTML"

• disable_notification (선택): 메시지를 무음으로 보내기

사용 예시:

// Uses DEFAULT_CHAT_ID from environment
await send_telegram_message({ text: "Task completed!" })

// Send to specific chat (overrides DEFAULT_CHAT_ID)
await send_telegram_message({ text: "Hello!", chat_id: "123456789" })

// Send with Markdown formatting
await send_telegram_message({ 
  text: "*Bold* and _italic_ text", 
  parse_mode: "Markdown" 
})

알림을 받게 되는 경우

Claude Code는 다음과 같은 경우 알림을 보냅니다:

• 명시적으로 요청한 경우: "끝나면 알려줘" 또는 "Telegram으로 알려줘"

• 실행 중 오류가 발생한 경우

• 중요한 이정표에 도달한 경우

• 사용자 입력이나 개입이 필요한 경우

예시 시나리오

# You say: "Deploy to production and notify me when done"
# Result: 🤖 Claude Code Notification
#         Deployment completed successfully! The app is now live.

# You say: "Run all tests and let me know the results"
# Result: 🤖 Claude Code Notification
#         All tests passed! 52/52 tests successful.

# You say: "Process this data and notify me if there are any errors"
# Result: 🤖 Claude Code Notification
#         Error: Failed to process row 451 - invalid date format

알림 예시

CLAUDE.md 예시

Claude Code가 Telegram 알림을 효과적으로 사용하도록 하려면 CLAUDE.md에 다음을 추가하세요:

# Telegram Notifications

Use the mcp__telegram-notify__send_telegram_message tool to send notifications to Telegram.

- Always send a Telegram notification when:
  - A task is fully complete
  - You need user input to continue
  - An error occurs that requires user attention
  - The user explicitly asks for a notification (e.g., "notify me", "send me a message", "let me know")

- Include relevant details in notifications:
  - For builds/tests: success/failure status and counts
  - For errors: the specific error message and file location

- Use concise, informative messages like:
  - "✅ Build completed successfully (2m 34s)"
  - "❌ Tests failed: 3/52 failing in auth.test.ts"
  - "⚠️ Need permission to modify /etc/hosts"

개발

로컬에서 실행:

# Start local development server
pnpm dev

로컬 개발 시 Wrangler는 .dev.vars 파일에서 환경 변수를 자동으로 로드합니다.

배포 전에 모든 검사를 실행하세요:

pnpm build

이 명령은 다음을 실행합니다:

1. pnpm format - Biome으로 코드 포맷팅

2. pnpm lint:fix - 린트 문제 수정

3. pnpm cf-typegen - Cloudflare 타입 생성

4. pnpm type-check - TypeScript 타입 확인

서버 테스트:

# An unauthenticated request must return HTTP 401
curl -i http://localhost:8787/mcp

# Claude Code performs the authenticated MCP handshake and health check
claude mcp list

디버깅

인증 테스트

엔드포인트가 bearer 토큰 없이 요청을 거부하는지 확인할 수 있습니다:

curl -i http://localhost:8787/mcp

이 경우 401 Unauthorized가 반환되어야 합니다. 그런 다음 claude mcp list를 사용하여 인증된 클라이언트 연결을 확인하세요.

일반적인 문제

1. 401 Unauthorized: 클라이언트의 Authorization: Bearer ... 헤더가 Cloudflare 시크릿 MCP_AUTH_TOKEN과 일치하는지 확인하세요.

2. MCP 재연결 또는 타임아웃: 클라이언트가 HTTP 전송과 /mcp 엔드포인트를 사용하는지 확인하세요. 폐기된 /sse 엔드포인트가 아닌지 확인하세요.

3. Telegram 알림이 전송되지 않음: Worker 환경에서 BOT_TOKEN과 DEFAULT_CHAT_ID가 올바르게 설정되었는지 확인하세요.

기술 세부 사항

• 언어: TypeScript (ES2021 타겟)

• 런타임: Node.js 호환성을 갖춘 Cloudflare Workers

• 프로토콜: MCP (Model Context Protocol)

• 전송 방식: 무상태 Streamable HTTP

• 관찰 가능성: 모니터링 활성화

참고 자료

이 프로젝트는 다음 가이드를 참고하여 구축되었습니다:

• 원격 MCP 서버 구축 - Cloudflare Agents

• Model Context Protocol (MCP) - Cloudflare Agents

• MCP 전송 방식 - Cloudflare Agents

• Cloudflare MCP 템플릿 (remote-mcp-authless)

라이선스

MIT