Telegram MCP 서버: AI 에이전트에게 Telegram Bot API 전체를 안전하게 제공하는 방법

AI 에이전트에게 Telegram 래퍼가 필요한 이유

AI 에이전트는 실제 도구를 다루는 데 점점 능숙해지고 있습니다. 대시보드를 읽고, 무엇이 중요한지 판단하고, 다음 단계를 실행할 수 있습니다. 하지만 Telegram 안에서 행동하려면 연결 다리가 필요합니다. "AMA 공지를 고정하고 질문 토픽을 열어 줘" 같은 문장을 올바른 Telegram API 호출로 바꿔 주는 무언가입니다.

그 다리가 바로 Telegram MCP 서버 입니다.

Model Context Protocol(MCP)은 Claude, ChatGPT, Cursor, Codex 같은 AI 클라이언트가 도구를 찾고 호출할 수 있게 해 주는 개방형 표준입니다. Telegram MCP 서버는 Telegram 작업을 이러한 도구로 제공하며, 모델이 따를 수 있는 명확한 설명과 입력 스키마를 함께 제공합니다.

이제 Metricgram이 이미 여러분의 그룹을 관리하는 봇을 기반으로 이 서버를 직접 호스팅합니다.

"Telegram Bot API 래핑"에 실제로 필요한 것

서류상으로는 에이전트를 위해 Bot API를 래핑하는 일이 쉬워 보입니다. 하지만 실제로는 다음이 필요합니다.

• 봇을 호스팅하고, 토큰을 안전하게 보관하며, 계속 실행 상태로 유지하기.
• 웹훅이나 폴링으로 업데이트 받기.
• 에이전트가 사용할 모든 엔드포인트마다 도구 정의 작성하기.
• 에이전트가 절대 건드리면 안 되는 채팅에 게시하지 못하도록 막기.
• 속도 제한, 이전된 슈퍼그룹, Telegram 오류 메시지 처리하기.
• 불안정한 네트워크 호출 한 번으로 같은 메시지가 두 번 게시되지 않도록 재시도를 안전하게 만들기.
• 나중에 설명해야 할 때를 대비해 에이전트가 한 일을 기록하기.

대부분의 팀은 "메시지 보내기"에서 멈춥니다. 나머지는 엄청난 양의 배관 작업이기 때문입니다. 결국 말은 할 수 있지만 커뮤니티를 제대로 관리하지는 못하는 에이전트가 만들어집니다.

Metricgram Telegram MCP 서버의 작동 방식

Metricgram은 이미 관리자 봇(또는 직접 만든 커스텀 봇)으로 여러분의 Telegram 그룹 안에 있습니다. MCP 서버는 AI 클라이언트가 호스팅 엔드포인트를 통해 그 봇을 사용할 수 있게 해 줄 뿐입니다.

1. 그룹을 Metricgram에 연결 하고 봇에 관리자 권한을 부여합니다.
2. AI 클라이언트에 엔드포인트 https://metricgram.com/api/v1/mcp를 추가합니다. 예를 들어 Claude에서는 커스텀 커넥터로 추가할 수 있습니다.
3. 로그인 후 OAuth로 액세스를 승인 합니다. 이게 전부입니다. 서버, 웹훅, 토큰을 관리할 필요가 없습니다. OAuth를 지원하지 않는 클라이언트는 아래 구성으로 API 키를 대신 사용할 수 있습니다.

{
  "mcpServers": {
    "metricgram": {
      "url": "https://metricgram.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop 사용자는 mcp-remote로 같은 엔드포인트에 연결할 수 있습니다. 클라이언트별 정확한 스니펫은 관리자 대시보드의 MCP 페이지에 있습니다.

70개 이상의 Bot API 메서드, 두 가지 호출 방식

서버는 Telegram Bot API를 두 개의 계층으로 제공합니다.

일상 업무를 위한 타입 지정 도구

자주 쓰는 작업에는 설명이 잘 된 파라미터를 갖춘 전용 도구가 있어 모델이 올바르게 사용하기 쉽습니다.

• send_telegram_message: 토픽, 답장, URL 버튼 지원
• send_telegram_media: 사진, 동영상, GIF, 문서, 오디오, 스티커
• send_telegram_poll: 투표와 퀴즈
• edit_telegram_message, delete_telegram_messages, react_to_telegram_message
• pin_telegram_message 및 forward_telegram_message
• manage_forum_topic: 토픽 생성, 이름 변경, 닫기, 다시 열기, 삭제
• get_telegram_chat 및 get_telegram_chat_member: 실시간 채팅 데이터
• handle_telegram_join_request, create_telegram_invite_link, update_telegram_chat_settings

전체 Bot API 게이트웨이

그 밖의 모든 작업은 telegram_bot_api를 거칩니다. 에이전트는 공식 Bot API 메서드 이름과 파라미터를 전달합니다. 예를 들어 setChatPermissions, banChatSenderChat, editMessageMedia, hideGeneralForumTopic, revokeChatInviteLink 등입니다. 보조 도구인 telegram_api_methods는 현재 키로 사용할 수 있는 모든 메서드를 보여 주므로, 에이전트는 무엇을 쓸 수 있는지 항상 알 수 있습니다.

보안: 에이전트가 chat_id를 고르지 않는 이유

가장 중요한 설계 결정은 에이전트가 할 수 없는 일입니다.

• 채팅이 고정됩니다. 에이전트는 Metricgram group_id를 전달합니다. 서버는 여러분이 소유한 그룹에서 Telegram chat_id를 도출하고 다른 채팅은 모두 거부합니다.
• 전달과 인용을 검사합니다. 메시지는 내 그룹에서만 전달, 복사, 인용할 수 있습니다.
• 봇 전체에 영향을 주는 작업은 제외됩니다. 웹훅, 결제, 봇 프로필 변경, 그룹 나가기는 제공되지 않습니다.
• 버튼은 안전합니다. 인라인 버튼은 URL을 열거나 텍스트를 복사할 수 있지만, 봇으로 콜백을 보낼 수는 없습니다.
• 권한 범위는 신뢰 수준에 맞춥니다. telegram:read, telegram:write, telegram:moderate, telegram:admin은 서로 분리되어 있어 권한이 다른 여러 키를 둘 수 있습니다.
• 재시도는 멱등적입니다. 쓰기 도구는 idempotency_key를 지원하므로, 재시도된 호출은 두 번 실행되지 않고 첫 번째 결과를 반환합니다.
• 모든 호출이 기록됩니다. 사용된 도구와 Bot API 메서드도 함께 남습니다.

에이전트는 공식 Bot API를 통해 봇으로 동작하며, 절대 여러분의 개인 Telegram 계정으로 동작하지 않습니다.

일반 봇에는 없는 컨텍스트

단순한 Bot API 래퍼는 행동은 할 수 있지만 볼 수 있는 것이 많지 않습니다. Metricgram MCP 서버는 커뮤니티 인텔리전스도 함께 제공합니다.

• 분석 개요와 활동 시계열
• 활성 멤버, 멤버 기록, 수집된 메시지
• 게이미피케이션 순위와 보상
• 그룹에서 일어난 일에 대한 AI 요약
• Stripe 구독자 상태와 이탈 위험이 있는 갱신

즉, 에이전트가 "이번 달에 참여를 멈춘 사람은 누구야?"에 답한 뒤 그들에게 정성스러운 메시지를 보내는 일까지 하나의 대화에서 처리할 수 있습니다.

워크플로 예시

주간 공지. "Crypto Talk에 주간 AMA 공지를 올리고, 모두에게 알리지 않고 고정한 뒤, AMA 질문 토픽을 열고 금요일에 만료되는 초대 링크를 만들어 줘."

관리 점검. "최근 메시지 200개에서 스팸 링크를 찾아 삭제하고 보낸 사람을 24시간 동안 제한해 줘."

커뮤니티 리포트. "이번 주와 지난주 활동을 비교하고, 가장 활발한 멤버 5명을 정리한 다음 General 토픽에 짧은 감사 메시지를 올려 줘."

가입 요청 분류. "활성 구독자인 사용자의 대기 중인 가입 요청은 승인하고 나머지는 거절해 줘."

이런 분들께 추천합니다

• 커뮤니티 운영자: 반복적인 관리 업무를 처리해 줄 어시스턴트가 필요한 분.
• 에이전시: 여러 클라이언트 그룹을 관리하며 하나의 에이전트로 모두 처리하고 싶은 분.
• 지원 및 고객 성공팀: Telegram에서 고객 커뮤니티를 운영하는 팀.
• 개발자: 봇 인프라를 운영하지 않고 에이전트 스택에 Telegram을 넣고 싶은 분.

시작하기

MCP 서버는 모든 Metricgram 플랜과 14일 무료 체험에 포함되어 있어 결제 전에 에이전트를 연결해 볼 수 있습니다. 대부분의 클라이언트는 OAuth로 연결합니다. 서버 URL을 붙여 넣고 로그인한 뒤 액세스를 승인하면 됩니다. OAuth를 지원하지 않는 클라이언트를 위해 API 키도 계속 제공됩니다.

Telegram MCP 서버 페이지와 MCP 기능 개요에서 자세히 알아본 뒤, 관리자 대시보드에서 첫 번째 키를 만들어 보세요.