chigwell/telegram-mcp
Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.
Telegram MCP Server – 개요
Telegram MCP는 AI 에이전트(Claude, Cursor 또는 Model Context Protocol(MCP)을 말하는 모든 클라이언트)가 Telegram 계정을 네이티브 도구 세트인 것처럼 상호 작용할 수 있게 하는 자체 호스팅 Python 서버입니다. MCP 도구 호출을 Telethon 기반 Telegram API 작업으로 변환하여 Telegram에서 할 수 있는 모든 것(채팅 읽기, 메시지 보내기, 그룹 관리, 연락처, 미디어, 폴더, 이벤트, 음성-텍스트 전사까지)을 노출합니다.
핵심 아이디어
- MCP ↔ Telegram 브리지 – 서버는 오픈 소스 Model Context Protocol을 구현하여 Telegram 작업을 LLM 기반 에이전트가 호출할 수 있는 구조화된 JSON 기반 도구로 변환합니다.
- 에이전트 친화적 – 결과는 정리된 JSON이며, 서버는 특수 오류 객체(예:
telegram_premium_required)를 보고하여 에이전트가 동작을 조정할 수 있습니다.
이것으로 할 수 있는 것
| 영역 | 예시 기능 |
|---|---|
| 계정 | 여러 구성된 계정을 나열하고 레이블로 호출을 라우팅합니다. |
| 채팅 및 그룹 | 채팅 나열, 그룹 생성/참여/탈퇴, 관리자, 금지, 느린 모드, 주제, 초대 링크, 읽음 확인 등 관리. |
| 메시지 | 보내기, 편집, 삭제, 전달, 예약, 고정, 반응, 투표 생성, 답장, 검색, 컨텍스트 가져오기, 리치 서식(표, 수식, 접이식 섹션이 포함된 Markdown/HTML) 사용 – 프리미엄 전용. |
| 연락처 | 나열, 검색, 추가, 차단, 가져오기/내보내기, 별칭 기억(예: 별칭을 가르친 후 send_message("андрей бекендер", …)가 작동). |
| 미디어 | 파일, 스티커, GIF, 음성 메모 업로드/다운로드, 4가지 엔진 중 하나를 사용한 음성/비디오 전사(Groq Whisper, Telegram Premium, OpenAI 호환 또는 로컬 Faster-Whisper). |
| 프로필 및 개인정보 | 프로필 정보, 사진, 개인정보 설정, 봇 명령 가져오기/설정. |
| 폴더 및 초안 | 폴더 나열, 생성, 재정렬, 삭제; 초안 저장, 나열, 지우기; 백업/복원을 위한 폴더 정의 스냅샷. |
| 이벤트 | 새 메시지 대기(wait_for_new_message), 또는 파일을 모니터링할 수 있는 에이전트(예: Claude Code)를 위해 JSON 라인을 파일에 쓰는 콜백 스타일 수신 피드 활성화. |
| 사용자 지정 이모지 및 탭 가능한 날짜 | 사용자 지정 이모지 ID를 검색하고 <tg-emoji> 태그로 재사용; format_date로 탭 가능한 날짜 칩을 삽입. |
음성 전사 세부 사항
- Groq – 호스팅된 Whisper-large-v3-turbo,
GROQ_API_KEY필요. 기본적으로 업로드 25 MiB 제한. - Telegram – Telegram Premium의 네이티브 전사 사용(무료, Telegram에 유지)하지만 마지막 세그먼트가 누락될 수 있음.
- OpenAI – 모든
/audio/transcriptions엔드포인트(OpenAI, Parakeet, LocalAI 등). - Whisper – 로컬 Faster-Whisper 모델(
pip install 'telegram-mcp[whisper]').
전사는 SQLite 파일에 캐시되며, 반복 요청은 캐시에 적중하고 동시 동일 요청은 병합됩니다.
빠른 시작
- 클론 및 설치 –
git clone https://github.com/chigwell/telegram-mcp.git && uv sync(Python 3.10+ 필요). - 세션 문자열 생성 –
uv run session_string_generator.py(QR 코드 또는 전화번호 흐름). - 구성 –
.env.example을.env로 복사하고TELEGRAM_API_ID,TELEGRAM_API_HASH,TELEGRAM_SESSION_STRING을 입력. - 실행 –
uv run telegram-mcp(또는 Docker – 아래 참조). - 선택 사항 – 장기 실행 서버를 위해 영구 SQLite 세션으로 마이그레이션(
uv run telegram-mcp-migrate-session).
배포 옵션
- Docker – 공식 이미지 자동 빌드;
data/transcripts(전사 캐시) 및 상태 디렉토리(~/.local/state/telegram-mcp)용 볼륨 마운트. - 다중 계정 –
.env에서 여러 계정 정의(예:ACCOUNT_1_LABEL,ACCOUNT_2_LABEL),account인수로 호출 라우팅. - 프록시 지원 –
TELEGRAM_PROXY를 SOCKS/HTTP 프록시 URL로 설정. - 보안 – 별칭, 세션 데이터, 수신 피드 로그를 저장하는 파일은 소유자 전용 권한(600/700)으로 생성됩니다. README는 동일한 이름의 PyPI 패키지
telegram-mcp를 설치하지 말라고 경고합니다(관련 없음).
누가 사용할까?
- LLM 기반 개인 비서 – Telegram 메시지를 읽거나 조치해야 하는 경우(예: Claude Code, Cursor, 사용자 지정 MCP 호스트).
- 자동화 엔지니어 – 여러 Telegram 계정에서 작동하는 봇을 구축하고 로직을 하드코딩된 스크립트가 아닌 LLM에 유지.
- 연구자 – 명시적 오류 객체와 개인정보 보호 중심 설계(허용 목록 채팅 액세스, 별칭 확인 등) 덕분에 LLM이 실제 메시징 플랫폼과 안전하게 상호 작용하는 방법을 탐구.
라이선스 및 커뮤니티
- 라이선스: Apache 2.0 – 상업 및 연구 용도에 허용적.
- 상태: 적극적으로 유지 관리(GitHub Actions로 린팅, Docker 빌드, CI). 풀 리퀘스트를 통한 기여를 환영합니다.
TL;DR
Telegram MCP Server는 Telegram을 풍부한 MCP 호환 도구 세트로 변환하는 Python 브리지로, LLM 에이전트가 Telegram 콘텐츠를 프로그래밍 방식으로 읽고, 쓰고, 관리하고, 전사할 수 있게 합니다. 다중 계정, 리치 서식, 사용자 지정 이모지, 안전하고 캐시 인식 음성 전사를 지원합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트