telegram-bot-mcp

Claude가 Telegram Bot API를 통해 Telegram 채널을 관리할 수 있게 해주는 MCP 서버 — 구독자 증가를 일별로 추적하고, 게시물을 발행·수정·고정·삭제할 수 있습니다.

🇮🇷 راهنمای فارسی · 배포 가이드 · راهنمای دپلوی

이게 뭔가요

Telegram Bot API는 일반 HTTPS API입니다. 이 저장소는 이를 Model Context Protocol로 감싸서 AI 어시스턴트가 도구로 호출할 수 있게 합니다 — "이번 주 채널 성과가 어땠어?"라고 물으면 curl https://api.telegram.org/bot.../getChatMemberCount 대신 답을 얻을 수 있습니다.

동일한 도구 정의에서 두 가지 형태로 제공됩니다:

매일 보고서를 사용자 개입 없이 실행하려면 원격 서버를 선택하세요. Claude Code만 사용하고 데이터가 머신 밖으로 나가는 것을 원하지 않는다면 플러그인을 선택하세요.

도구

두 빌드 모두 동일한 8가지 도구를 제공합니다.

빠른 시작 (원격 서버)

1. @BotFather로 봇 생성 → /newbot → 토큰 복사.

2. 채널의 관리자로 봇 추가.

3. val.town에서 HTTP val 생성 후 remote/telegram-mcp.ts 붙여넣기.

4. val 사이드바에서 환경 변수 3개 설정: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.

5. Claude에서: 설정 → 커넥터 → 커스텀 커넥터 추가 → https://<your-val>.web.val.run/mcp → 비밀번호 입력.

로컬 플러그인 경로와 문제 해결을 포함한 전체 가이드: docs/deployment.md.

보안

이 저장소에는 어떤 자격 증명도 커밋되지 않습니다. config.json과 .env는 gitignore 처리되어 있으며, .example 파일만 추적됩니다. 포크를 푸시하기 전에 git status로 둘 중 어느 것도 나타나지 않는지 확인하세요.

원격 서버는 인터넷에 개방된 채로 두지 않고 완전한 OAuth 2.1 인증 흐름을 구현합니다:

• 유효한 bearer 토큰이 없는 요청은 RFC 9728에 따라 리소스 메타데이터를 가리키는 WWW-Authenticate 헤더와 함께 401을 받습니다.

• 클라이언트는 동적으로 등록됩니다 (RFC 7591); 배포할 클라이언트 시크릿이 없습니다.

• 인증 코드는 PKCE(S256)로 보호되며, 리디렉션 URI는 등록된 집합에 대해 검증됩니다.

• 액세스 및 리프레시 토큰은 HMAC-SHA256 서명된 무상태 토큰입니다 — 액세스 24시간, 리프레시 30일.

• 동의 화면은 사용자가 선택하는 MCP_PASSWORD로 게이트됩니다.

봇 토큰은 호스트의 환경 변수에 남아 있으며 어떤 도구에서도 반환되지 않습니다.

MCP_PASSWORD를 채널의 비밀번호처럼 취급하세요. 이 값을 가진 사람은 누구나 연결하여 게시물을 발행할 수 있습니다.

제한 사항

Bot API는 구독자 수만 보고합니다. 게시물 조회수, 전달, 도달 범위, Telegram 공식 채널 통계 그래프는 봇에 노출되지 않습니다 — 이러한 기능은 채널을 관리하는 사용자 계정으로 로그인한 MTProto 클라이언트가 필요합니다.

봇은 일반적으로 자신이 보낸 메시지만 편집할 수 있습니다. Telegram은 can_edit_messages 관리자 권한("다른 사용자의 메시지 편집 가능, 채널 전용")을 정의하지만, 인간 관리자가 게시한 게시물에 대한 봇의 동작은 명확하게 문서화되어 있지 않습니다 — 신뢰하기 전에 자신의 채널에서 테스트하세요. 삭제는 다릅니다: can_delete_messages는 다른 사용자의 메시지를 명시적으로 포함합니다.

성장 비교에는 실행 간에 기록 저장소가 유지되어야 합니다. Val Town에서는 blob 스토리지이며 영구적입니다. 로컬 플러그인에서는 CSV 파일입니다 — 임시 디렉토리가 아닌 영구적인 위치에 보관하세요.

저장소 구조

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

테스트

npm test

Node 22.6+ 필요. 22개 검사가 OAuth 흐름(401 챌린지, 디스커버리 문서, 동적 등록, PKCE 거부, 토큰 및 리프레시 승인, 위조 토큰 거부)과 MCP 프로토콜(initialize, notifications, 도구 목록, 성장 델타 산술, 도구 오류 경로)을 다룹니다. Telegram API는 모킹됩니다; 네트워크 액세스나 실제 봇 토큰이 필요 없습니다.

테스트 스위트는 배포된 소스 자체에 대해 실행됩니다 — tests/build.mjs는 정확히 한 줄, Val Town blob import만 다시 작성하며 다른 것은 변경하지 않습니다.

라이선스

MIT