tgread

읽기 전용 Telegram MCP 서버입니다. Claude Code가 채널, 그룹, DM을 읽을 수 있게 해주며, 쓰기 수단은 전혀 제공하지 않습니다.

./install.sh          # pinned venv + ~/.local/bin/tgread + MCP registration
tgread login          # api_id/api_hash, phone, code, 2FA
tgread status         # who am I, is the session live, are perms sane

기존 서버를 쓰지 않는 이유

좋은 커뮤니티 서버들이 있습니다 — chigwell/telegram-mcp는 별 1.5k개, 기여자 30명, 그리고 제대로 된 릴리스 관리 체계를 갖추고 있습니다. 이 서버를 직접 작성한 이유는 그 코드를 불신해서가 아닙니다. 직접 작성함으로써 얻는 진짜 이점은 의존성 수가 아니라 도구 표면과 검토 가능성이며, 프로세스가 Telegram 세션을 보유하고 에이전트에게 공격자가 통제한 텍스트를 공급할 때 중요한 것은 바로 이 두 가지입니다.

MTProto를 직접 작성하는 것은 무모한 일입니다 — Telethon이 바로 암호화, DC 마이그레이션, 재연결 로직이기 때문입니다. 그래서 Telethon은 유지합니다. 그 위의 모든 것은 우리 것이 됩니다.

Related MCP server: telegram-mcp-server

위협 모델

채널을 읽는다는 것은 공격자가 선택한 텍스트가 셸을 보유한 에이전트에 유입된다는 뜻입니다 — 그리고 일반적으로 연결된 다른 모든 것(메일, 메모, 클라우드 자격 증명)에도 유입됩니다. 이것이 여기서 지배적인 위험이며, 서버를 누가 작성했는지에 따라 해결되지 않습니다. 쓰기 표면이 없는 서버를 선택하는 것은 모델이 잘 작동하는 것에 의존하지 않는 몇 안 되는 완화책 중 하나입니다.

flowchart TD
    A["hostile channel post<br/>'ignore previous instructions…'"] --> B["tgread read_chat"]
    B --> C["UNTRUSTED envelope<br/>wrapped around every payload"]
    C --> D["agent context"]
    D --> E{"agent tries to act on it"}
    E -->|"send / delete / join"| F["no such tool exists<br/>tools/call → isError"]
    E -->|"raw TL request"| G["guard at _call → WriteBlocked"]
    E -->|"summarise for the user"| H["fine — this is the intended path"]
    style F fill:#1f6f43,color:#fff
    style G fill:#1f6f43,color:#fff

세 개의 계층, 버그가 발생해도 견딜 수 있는 정도가 커지는 순서:

1. 쓰기 도구가 광고되지 않습니다. 주입된 지시가 호출할 대상이 없습니다.

2. 모든 페이로드는 UNTRUSTED CONTENT 배너로 감싸져 지시가 아닌 데이터임을 명시합니다 — 공격자가 통제하는 채팅 제목과 소개(bio)도 포함됩니다.

3. 전송 가드. Telethon은 모든 아웃바운드 TL 요청을 TelegramClient._call을 통해 흘려보냅니다(68개의 내부 호출 지점이 await self(req)를 통해 도달하며, __call__은 한 줄짜리 위임자입니다). ReadOnlyClient가 이를 재정의합니다. 이 파일의 버그가 있어도 계정을 변경할 수 없습니다.

가드는 기본적으로 차단(fail closed) 합니다. TL 클래스 이름이 Get/Search/Resolve/Check/Find로 시작하거나 9개 항목의 인프라 허용 목록에 있는 경우가 아니면 요청이 거부됩니다. 읽기처럼 보이지만 다른 사람이 관찰할 수 있는 효과가 있어 이름으로 거부되는 세 가지 요청이 있습니다 — GetMessagesViews(공개 조회수 카운터 증가), GetBotCallbackAnswer(인라인 버튼 누름), GetInlineBotResults(사용자로서 봇에 질의). 중첩 요청도 검사되므로 허용된 InvokeWithLayer 래퍼 안에 쓰기가 숨어들 수 없습니다.

flowchart LR
    R["TL request"] --> W["walk nested .query"]
    W --> D{"in EXPLICIT_DENY?"}
    D -->|yes| X["WriteBlocked"]
    D -->|no| I{"in INFRA_ALLOW?"}
    I -->|yes| P["to the wire"]
    I -->|no| V{"starts with Get/Search/<br/>Resolve/Check/Find?"}
    V -->|yes| P
    V -->|"no — incl. every<br/>name we've never seen"| X
    style X fill:#8b2020,color:#fff
    style P fill:#1f6f43,color:#fff

tgread check는 이 검사를 오프라인으로 실행합니다: 쓰기 요청 26개 차단, 읽기 17개 허용, 알 수 없는 이름은 기본 차단, 중첩 검사. 네트워크도, 세션도, 자격 증명도 필요 없습니다.

도구

미디어 다운로드는 의도적으로 없습니다: 첨부 파일을 가져오는 것은 공격자가 선택한 바이트를 에이전트의 파일 시스템에 쓰는 것을 의미하기 때문입니다. 메시지 메타데이터는 미디어 유형만 보고합니다.

운영 참고 사항

• 보조 계정을 사용하세요. 유저봇(공식 앱이 아닌 모든 MTProto 클라이언트)은 ToS 위반으로 차단될 수 있습니다. 이 위험은 여기 나열된 모든 서버에 동일하게 적용됩니다.

• 세션 파일은 계정 전체에 대한 베어러 토큰입니다. Telegram 비밀번호를 변경해도 세션은 무효화되지 않습니다. 로컬에서 삭제하기 전에 서버 측에서 먼저 폐기하는 tgread logout 또는 설정 → 기기(Settings → Devices)만이 무효화할 수 있습니다. SSH 개인 키처럼 취급하세요.

• pip install telegram-mcp는 이 프로젝트도, chigwell의 프로젝트도 아닙니다. 그 PyPI 이름은 무관한 프로젝트에 속해 있습니다. 여기에 TELEGRAM_API_ID / TELEGRAM_API_HASH를 전달하면 자격 증명을 제3자 코드에 넘겨주는 셈입니다. 이 프로젝트의 어떤 것도 의도적으로 PyPI에 게시되지 않습니다.

• 상태는 하나의 디렉터리에 저장됩니다 — $TGREAD_STATE_DIR, 기본값 ~/.local/state/tgread, 권한 0700, config.env(0600)와 tgread.session(0600)을 보관합니다. chmod, 백업, 삭제할 때 하나의 디렉터리만 다루면 됩니다. tgread status는 권한이 어긋나면 이를 알려줍니다.

• install.sh는 uv sync --frozen을 사용합니다 — 커밋된 uv.lock에 있는 정확한 버전을 설치하며, 재해석(re-resolving) 대신 실패합니다. 조용히 새 업스트림 릴리스를 가져오는 해석기는 손상된 패키지가 세션을 보유한 프로세스에 도달하는 경로입니다.

구조

명령어

tgread login      interactive: API credentials, phone, login code, 2FA
tgread status     who am I, is the session valid, are permissions sane
tgread logout     revoke server-side, then delete locally
tgread check      offline self-test of the read-only guard
tgread serve      speak MCP over stdio — what Claude Code runs

login과 logout은 가드가 적용된 클라이언트가 아닌 일반 클라이언트를 사용합니다: 가드는 터미널에서 세션을 설정하거나 폐기하는 사람이 아니라 에이전트를 제한하기 위해 존재합니다. MCP 서버가 다루는 모든 것은 ReadOnlyClient를 거칩니다.