AI 에이전트에게 Telegram 데이터 접근 권한을 부여하는 방법 (MCP + REST API)

제 AI 에이전트가 Telegram 채널에서 메시지를 가져올 수 있어야 했습니다. 간단해 보였죠. 하지만 알고 보니 꽤나 골치 아픈 일이었습니다.

Bot API는 봇이 멤버로 추가되지 않으면 채널을 읽을 수 없게 제한합니다. Telethon이나 Pyrogram은 작동하지만, 직접 호스팅해야 하고, 전화번호 인증을 처리해야 하며, 세션 관리(session management)를 직접 돌봐야 합니다. 저는 그런 것들을 원하지 않았습니다. 그저 호출할 수 있는 REST 엔드포인트(endpoint)가 필요했을 뿐입니다.

결국 저는 RapidAPI의 이 Telegram API를 사용하게 되었습니다. 이 API는 MTProto(Telegram의 네이티브 프로토콜)를 기반으로 하며, 12개의 엔드포인트를 REST 및 MCP 도구(tools)로 노출하고, 월 2,500회 요청이 가능한 무료 티어(free tier)를 제공합니다. 저는 아직 그 무료 플랜을 사용 중이며 더 많은 양은 필요하지 않았습니다. 봇 토큰도, 전화번호도, 유지 관리해야 할 인프라(infra)도 필요 없습니다.

설정 방법은 다음과 같습니다.

제공되는 기능

연결되면 에이전트는 다음과 같은 작업을 수행할 수 있습니다:

모든 공개 Telegram 채널에서 메시지 읽기
키워드로 모든 공개 채널 검색
채널 상세 정보 가져오기: 멤버 수, 설명, 연결된 그룹
사용자 프로필 조회 (자기소개, 프리미엄 상태 등)

총 12개의 도구가 있으며, 모두 하나의 MCP 엔드포인트를 통해 사용할 수 있습니다.

아키텍처 (Architecture)

복잡한 구조는 아닙니다:

Your AI Agent  ──MCP──▶  TG Gateway API  ──MTProto──▶  Telegram
                         (12 tools)                     (public data)

API가 내부적으로 MTProto 세션, 계정 순환(account rotation), 속도 제한(rate limiting)을 처리합니다. 여러분은 그저 HTTP 호출만 하면 됩니다.

1단계: API 키 가져오기

대시보드에서 X-RapidAPI-Key를 복사하세요. 이것이 유일한 인증 정보입니다.

2단계: MCP를 통해 연결하기

Claude, LangChain, CrewAI 또는 n8n을 사용 중이라면 MCP를 통해 직접 연결할 수 있습니다. 엔드포인트는 Streamable HTTP(프로토콜 2025-06-18)를 사용합니다:

POST https://telegram-public-api.p.rapidapi.com/v1/mcp

먼저 세션을 초기화하세요:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
...

응답 헤더(response headers)에서 Mcp-Session-Id를 가져오세요. 이후의 모든 후속 호출(follow-up call) 시 이 값을 전달해야 합니다.

그다음 도구(tools) 목록을 조회합니다:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
...

다음과 같이 12개의 도구를 받게 됩니다:

도구 (Tool)	기능
`tg_resolve_username`	@username → peer ID
...

그리고 하나를 호출합니다:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
...

끝입니다. 이제 당신의 에이전트는 Telegram에 접근할 수 있습니다.

단계 3: 또는 간단히 Python 사용하기

만약 MCP가 귀하의 사례에 과하다면(overkill), Python 클라이언트가 있습니다:

pip install rapidapi-telegram

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")
...

get_*_by_username 헬퍼(helpers) 함수들이 매우 유용합니다. 이 함수들은 사용자 이름(username)을 확인(resolve)하고 데이터를 가져오는 과정을 한 번의 호출로 처리하므로, 요청을 수동으로 체이닝(chaining)할 필요가 없습니다.

이 기술로 실제로 만든 두 가지

채널 모니터 (Channel monitor)

매우 단순합니다. 매 분마다 채널을 폴링(Poll)하여 새로운 내용이 있으면 출력합니다:

from rapidapi_telegram import TelegramClient
import time

...

분당 1회 폴링 시, 하루에 약 1,440개의 요청을 소모합니다. 무료 티어(free tier)에서는 제한(cap)에 도달하기 전까지 약 40시간 동안 연속으로 실행할 수 있습니다. 무언가를 계속 지켜봐야 할 때 충분한 양입니다.

모든 채널 대상 키워드 알림

이 부분은 글로벌 검색(global search) 기능이 진가를 발휘하는 지점입니다:

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")
...

모든 공개 Telegram 채널을 한 번에 검색할 수 있습니다. Bot API로 이를 시도해 보세요 (스포일러: 불가능합니다).

Bot API vs. 이것: 빠른 비교

이 질문을 자주 받기에, 짧은 요약을 준비했습니다:

	Bot API	MTProto API
모든 공개 채널 읽기	아니요, 봇이 추가되어야 함	네, 모든 공개 채널 가능
...

단순히 봇을 통해 메시지를 보내기만 하면 된다면 Bot API로 충분합니다. 하지만 공개 데이터(채널, 메시지, 프로필)를 읽어야 한다면 MTProto가 정답입니다.

비용에 대하여

위의 모든 과정은 무료 티어 (free tier)에서 실행됩니다. 저는 아무것도 결제하지 않았습니다. 높은 처리량이 필요한 경우 유료 플랜이 있지만, 솔직히 개인 프로젝트나 프로토타이핑 용도로는 월 2,500회 무료 제공만으로도 충분합니다.

링크

이것을 활용해 무언가를 만드셨다면 댓글을 남겨주세요. 사람들이 이것을 어떤 용도로 사용하는지 궁금합니다.

Insights