telegram-mcp

Claude에게 한 Telegram 그룹의 최신 이미지를 전달합니다.

스크린샷은 봇이 게시하며, Telegram Bot API는 봇 자신의 메시지를 절대 반환하지 않습니다. 그래서 이 도구는 MTProto(Telethon)를 통해 사용자 계정으로 그룹을 읽습니다. 그 사진들을 보는 유일한 방법입니다.

설정 (1회)

1. https://my.telegram.org → API development tools에서 api id와 hash를 받습니다.

2. cp .env.example .env를 실행하고 TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_CHAT_ID(그룹의 숫자 ID, 음수)를 입력합니다.

3. 환경을 생성합니다:

python -m venv .venv
.venv\Scripts\pip install -e .[dev]

4. 로그인합니다 — Claude가 아닌 터미널에서:

.venv\Scripts\telegram-mcp-login

전화번호, Telegram이 보낸 코드, 그리고 2단계 인증 비밀번호가 있다면 그것을 묻고, session/telegram.session을 작성합니다.

또한 대화 목록을 한 번 나열하고 그룹 이름을 다시 출력합니다. 이 목록 덕분에 세션이 나중에 슈퍼그룹을 해석할 수 있습니다 -- 봇이 그룹에 합류하는 즉시 Telegram이 그룹을 슈퍼그룹으로 전환합니다 -- 그리고 그 이름은 TELEGRAM_CHAT_ID가 생각한 대상을 가리키는지 확인해 줍니다. 그룹을 찾을 수 없으면 그렇게 알리고 0이 아닌 코드로 종료합니다.

Related MCP server: telegram-user-mcp

Claude에 설치

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

사용자 범위이므로 모든 프로젝트에서 사용할 수 있습니다.

도구

• get_latest_image() — 그룹에서 가장 최근 사진, 200개 메시지를 거슬러 올라가 확인합니다.

• wait_for_next_image(timeout_seconds=120) — 호출 시점보다 새로운 사진이 도착할 때까지 차단합니다. 대기에는 토큰이 들지 않습니다. 프로세스는 소켓에서 대기 상태로 있습니다. MCP 클라이언트의 도구 타임아웃 안에 머물도록 1~240초로 제한됩니다.

둘 다 이미지(JPEG, 긴 변 ≤1568px)와 텍스트 한 줄을 반환합니다: 먼저 수정되지 않은 원본의 경로, 그다음 메시지 ID, 타임스탬프, 보낸 사람, 그리고 인용된 캡션입니다. 축소 시 작은 글씨가 사라지면 원본을 잘라내세요.

한 번에 하나의 프로세스만 세션을 보유할 수 있습니다. 첫 번째 세션이 호출 중일 때 두 번째 Claude Code 세션이 도구를 호출하면 SQLite 오류를 받는 대신 잠시 후 다시 시도하라는 안내를 받습니다.

테스트

.venv\Scripts\python -m pytest

네트워크도 Telegram 계정도 필요 없습니다 — Telethon은 전체가 페이크 처리됩니다.

보안

session/telegram.session은 Telegram 계정에 대한 전체 로그인입니다. gitignore 처리되어 있으며 이 머신을 벗어나지 않습니다. 이 파일을 가진 사람은 누구나 메시지를 읽을 수 있습니다. 복사된 것으로 의심되면 삭제하고 로그인을 다시 실행하세요. 자격 증명은 .env에만 존재합니다 — 문서, 프롬프트, 티켓에는 절대 넣지 마세요.