Telegram 계정 프록시 사용 가이드

Telegram 계정 프록시는 본인이 소유한 개인 Telegram 계정에 독립적이고 상주하는 MCP 및 REST 인터페이스를 제공합니다. 각 인스턴스는 하나의 계정만 서비스하며, 컨테이너에는 AI가 포함되어 있지 않고 로그인 세션은 해당 인스턴스의 독립적인 영구 볼륨에 저장됩니다.

이것은 Telegram Bot API 봇이 아닙니다. 스팸 메시지, 대량 콜드 메시지 발송 또는 Telegram 제한 우회에 사용하지 마세요. 제3자에게 콘텐츠를 전송, 편집 또는 삭제하기 전에 Agent가 명확한 확인을 받아야 합니다.

배포 및 로그인

콘솔 → 애플리케이션에서 Telegram 계정 프록시를 생성하고, 구독을 활성화한 후 배포를 클릭합니다. 인스턴스 리소스는 플랫폼에서 자동으로 구성합니다.
인스턴스가 준비되면 「로그인 QR 코드 생성」을 클릭합니다. QR 코드는 단기간 유효하며, 만료 후 다시 생성할 수 있습니다.
Telegram에서 설정 → 기기 → 데스크톱 기기 연결을 열고 QR 코드를 스캔합니다.
상태가 password_required로 변경되면 콘솔에서 Telegram 2단계 인증 비밀번호를 입력합니다. 비밀번호는 테넌트 인스턴스에만 제출되며, 플랫폼 구성에 기록되지 않습니다.
상태가 authenticated로 변경되면 콘솔에 현재 계정, MCP 주소 및 Bearer 액세스 토큰이 표시됩니다.

인증 세션은 영구 볼륨에 저장되며, 정상적인 재시작과 업그레이드 시 재사용됩니다. 콘솔의 「계정 로그아웃」은 /api/auth/logout을 호출하여 Telegram 세션을 취소하며, 「인스턴스 삭제」는 워크로드와 영구 볼륨도 삭제합니다.

인증 및 상태 확인

/health 및 /readyz를 제외하고 로그인, REST 및 MCP 인터페이스는 모두 다음을 요구합니다:

Authorization: Bearer <액세스 토큰>

서비스는 요청 헤더 인증만 허용하며, 토큰을 URL에 붙이는 방식은 지원하지 않습니다. 계정 비밀번호와 동일하게 보호하세요.

curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health는 HTTP 프로세스가 실행 중임만 나타냅니다:

{"status":"ok"}

/readyz는 MTProto 연결 사용 가능 여부를 나타냅니다. 연결된 경우 계정이 아직 QR 코드 스캔 중이거나 2단계 인증을 기다리는 상태여도 HTTP 200을 반환합니다:

{"status":"ready","gateway_connected":true,"login_state":"login_required"}

연결이 끊기면 Kubernetes의 Pod 직접 프로브는 HTTP 503을 반환하고, 인스턴스는 백그라운드에서 자동으로 재연결됩니다. 이때 Pod는 일시적으로 공개 Service에서 제거되므로 인스턴스 도메인을 통해 진단 JSON을 읽을 수 있다고 보장할 수 없습니다. 콘솔에서 Deployment가 Ready 상태로 복구될 때까지 기다리세요. login_state의 일반적인 값에는 login_required, waiting_scan, password_required, authenticated가 포함됩니다. 계정 메시지 작업을 수행하기 전에도 반드시 authenticated 상태에 도달해야 합니다.

MCP 클라이언트 연결

Claude Code

claude mcp add \
  --transport http \
  --header "Authorization: Bearer <액세스 토큰>" \
  telegram \
  https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp

Cursor 등 정적 요청 헤더를 지원하는 클라이언트

클라이언트의 현재 문서에 따라 Streamable HTTP 주소를 구성하고 Authorization 요청 헤더를 추가하세요. 예를 들어 아래 구조를 지원하는 클라이언트는 다음을 사용할 수 있습니다:

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer <액세스 토큰>"}
    }
  }
}

이것은 모든 MCP 클라이언트에 공통으로 적용되는 구성 형식이 아닙니다. Claude Desktop / Claude.ai의 원격 커넥터는 클라우드에서 연결되며, 로컬 claude_desktop_config.json에 있는 어떠한 HTTP 요청 헤더도 읽지 않습니다. 현재 정적 Bearer 요청 헤더가 필요한 경우 Claude Code 또는 해당 기능을 명시적으로 지원하는 클라이언트를 사용하세요.

MCP 도구

도구	기능
`telegram_whoami`	현재 인증된 계정 확인
`telegram_list_chats`	최근 대화 목록 표시, 읽지 않은 항목만 볼 수 있음
`telegram_contacts`	연락처 목록 표시
`telegram_read_messages`	지정된 대화의 최근 메시지 읽기
`telegram_search_messages`	하나의 대화 또는 모든 대화 검색
`telegram_send_message`	메시지 전송, 지정된 메시지에 답장 가능
`telegram_edit_message`	현재 계정이 전송한 메시지 편집
`telegram_delete_message`	삭제 권한이 있는 메시지 삭제
`telegram_react`	Unicode 이모지로 메시지에 반응
`telegram_mark_read`	대화를 읽음으로 표시

target은 대화 ID, 사용자 이름 또는 정확한 대화 이름일 수 있습니다. 이름에 모호성이 있는 경우 ID 또는 사용자 이름을 우선적으로 사용하세요.

REST API

모든 성공 응답은 {"data": ...}를 사용하며, 실패 응답은 {"error": "..."}를 사용합니다.

예시

# 현재 계정
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# 최근 대화
curl "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/chats?limit=20&unread_only=false" \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# Saved Messages에 테스트 메시지 전송
curl -X POST https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"me","text":"Hello from my Telegram proxy"}'

전체 인터페이스

메서드 및 경로	주요 매개변수	기능
`POST /api/auth/qr`	—	로그인 QR 코드 URL 생성
`GET /api/auth/status`	—	로그인 상태 및 계정 정보 조회
`POST /api/auth/password`	`{password}`	2단계 인증 비밀번호 제출
`POST /api/auth/logout`	—	인스턴스에 저장된 세션 취소
`GET /api/whoami`	—	현재 계정 확인
`GET /api/chats`	`?limit=&unread_only=`	대화 및 읽지 않은 수 목록 표시
`GET /api/contacts`	—	연락처 목록 표시
`GET /api/chats/{target}/messages`	`?limit=`	메시지 읽기
`GET /api/messages/search`	`?q=&target=&limit=`	메시지 검색; target 생략 시 대화 간 검색
`POST /api/messages`	`{target,text,reply_to?}`	메시지 전송 또는 답장
`PATCH /api/chats/{target}/messages/{message_id}`	`{text}`	메시지 편집
`DELETE /api/chats/{target}/messages/{message_id}`	—	메시지 삭제
`POST /api/chats/{target}/messages/{message_id}/reactions`	`{emoji}`	Unicode 이모지 반응 추가
`POST /api/chats/{target}/read`	—	대화를 읽음으로 표시

자주 묻는 질문

401：Bearer 토큰이 누락되었거나 잘못되었습니다. 토큰이 URL 쿼리 매개변수가 아닌 요청 헤더에 있는지 확인하세요.
503：프록시 액세스 토큰이 구성되지 않았거나 Telegram 클라이언트가 아직 준비되지 않았습니다. 먼저 /readyz를 확인하세요. 프록시 액세스 토큰이 구성되지 않은 경우, 보호된 인터페이스도 503을 반환합니다.
400：매개변수 또는 JSON이 유효하지 않습니다. 검색에는 반드시 q를 제공해야 하며, limit는 1 이상인 정수여야 합니다.
403 / 404：현재 계정에 권한이 없거나 target / message ID가 존재하지 않습니다.
429：Telegram 빈도 제한이 트리거되었습니다. retry_after를 읽고 기다리며, 동시에 재시도하지 마세요.
QR 코드가 계속 완료되지 않음：QR 코드를 다시 생성하고 Telegram의 「데스크톱 기기 연결」 스캔 진입점을 사용하고 있는지 확인하세요.
재시작 후 다시 로그인을 요구함：인스턴스 영구 볼륨이 정상인지 확인하세요. 직접 로그아웃하거나 Telegram 기기 목록에서 세션을 취소했거나 세션이 만료된 후에는 다시 스캔해야 합니다.

검증 범위

소스 코드와 자동화 테스트는 로그인 상태, Bearer fail-close, REST 매개변수 검증, 오류 매핑 및 세션 영속화 구현을 포괄합니다. 프로덕션 사용 시에는 여전히 먼저 target=me（Saved Messages）에서 읽기 전용 및 메시지 생성/편집/삭제 smoke를 완료한 후, Agent가 제3자 세션을 조작하도록 허용해야 합니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Telegram 계정 프록시 사용 가이드

배포 및 로그인

인증 및 상태 확인

MCP 클라이언트 연결

Claude Code

Cursor 등 정적 요청 헤더를 지원하는 클라이언트

MCP 도구

REST API

예시

전체 인터페이스

자주 묻는 질문

검증 범위

​배포 및 로그인

​인증 및 상태 확인

​MCP 클라이언트 연결

​Claude Code

​Cursor 등 정적 요청 헤더를 지원하는 클라이언트

​MCP 도구

​REST API

​예시

​전체 인터페이스

​자주 묻는 질문

​검증 범위

배포 및 로그인

인증 및 상태 확인

MCP 클라이언트 연결

Claude Code

Cursor 등 정적 요청 헤더를 지원하는 클라이언트

MCP 도구

REST API

예시

전체 인터페이스

자주 묻는 질문

검증 범위