TelegramLens

텔레그램 채널의 종목 언급·내러티브 흐름을 구조화해 AI(Claude)에게 전달하는 로컬 MCP 서버.

AI는 이미 퍼져 있는 정보를 정리할 뿐, 아직 구조화되지 않은 내러티브 흐름은 못 잡는다. 텔레그램에서 도는 찌라시·모멘텀·테마를 구조화해 던져주면 그 갭을 메운다.

비공개·판매용 (Proprietary). 공개 배포하지 않는다.

구조

사용자 Telegram 계정 (Telethon 세션, 로컬)
    → 가입한 채널 메시지 수집
    → 종목 언급 추출 (KRX 2700+ 종목 사전 검증)
    → 로컬 SQLite (히스토리 보존 → 모멘텀 감지)
    → MCP 툴로 Claude에 구조화 요약 제공

데이터는 전부 사용자 PC(~/.telegramlens/)에만 저장된다. 서버로 보내지 않는다.

Related MCP server: Telegram MCP Server

설치 & 로그인

pip install -e .

# 1) Telegram API 자격증명 발급: https://my.telegram.org → API development tools
# 2) 로그인 (전화번호 인증 — 1회만)
telegramlens-login

로그인하면 세션 파일·DB·종목 사전(KRX)이 ~/.telegramlens/ 에 준비된다.

Claude 등록

telegramlens-setup           # Claude Desktop/Code 자동 등록

또는 수동으로 claude_desktop_config.json:

{ "mcpServers": { "telegramlens": { "command": "telegramlens" } } }

백그라운드 자동 수집 (별도 자식 데몬)

수동 telegram_sync 를 매번 부르지 않아도, Claude 가 이 MCP 서버를 켜둔 동안 수집 데몬이 10분 주기로 백그라운드 수집한다. 삭제되기 전 찌라시를 박제하고 momentum 히스토리를 쌓는 게 목적. 데몬이 DB를 미리 채워두므로 조회 도구는 즉시 응답한다(질문할 때 텔레그램 접속을 기다리지 않는다).

왜 '별도 자식 프로세스'인가. 두 함정을 동시에 피하려는 설계다:

1. 백신(persistence) — 데몬을 창 없이 detach 하거나 부팅 자동시작(Run키/예약작업)을 걸면, 행위가 멀웨어의 persistence/defense-evasion 패턴과 같아 행위 엔진(예: AhnLab V3 Persistence/MDP.Event)에 잡힌다.

2. stdio 오염·멈춤 — 반대로 수집을 MCP 서버 안에서 돌리면, Telethon 로그가 stdout(= Claude 와의 JSON-RPC 채널)을 오염시키고 무거운 수집이 이벤트 루프를 막아 "응답 멈춤/용량" 에러가 난다.

그래서 데몬을 평범한 자식 프로세스로 띄운다 — detach·breakaway·자동시작 레지스트리가 전혀 없고(= persistence 아님), stdout/stderr 는 DEVNULL 로 막아(= stdio 오염 없음), 별도 프로세스라 서버 이벤트 루프를 막지 않는다(= 멈춤 없음). Claude(부모 MCP 서버)가 종료되면 함께 정리된다.

• 동작: 서버 기동 시 데몬 자식 1개 spawn → 데몬이 즉시 1회(백필) 후 10분 주기. 데몬이 떠 있는 동안 telegram_sync 는 세션을 데몬에 양보하고 DB 신선도만 보고한다.

• 공백 처리(정합성): Claude 를 닫으면 데몬도 종료. 다시 열면 데몬이 꺼져 있던 구간을 DB 최신 메시지 시각(watermark)부터 지금까지 자동 백필한다 — 시간 상한 최대 7일(--max-window), 채널당 상한은 창 길이에 비례해 자동 확대(정상 500 → 대형 캐치업 시 최대 5000)되어 바쁜 채널도 날짜 경계까지 빠짐없이 채운다(중복은 UNIQUE 제약으로 스킵). 긴 갭 백필은 첫 사이클이 수 분 걸릴 수 있고, 그동안 조회 도구는 "수집 중"을 안내한다.

• 상태: telegram_status 의 collector 필드. 로그: ~/.telegramlens/daemon.log.

• DB는 WAL 모드 — 수집(write)이 도는 중에도 Claude 조회(read)가 막히지 않는다.

디버그·옵트인용으로 포그라운드 수동 실행도 가능: telegramlens-daemon (콘솔 창에서 직접 실행). 자동 기동 데몬과 PID 락을 공유해 중복 실행은 막힌다. 자동시작(부팅) 등록 기능은 없다.

MCP 툴

조회

수집 대상은 가입된 모든 브로드캐스트 채널이다. 새로 가입한 채널은 다음 사이클부터 자동 포함된다(별도 등록 불필요).

채널 진단

사전 관리 (오탐·별칭 루프)

추출 품질 2층

사용자 사전은 ~/.telegramlens/aliases.json, ~/.telegramlens/ambiguous_codes.json 로 확장(번들 위에 병합).

알려진 한계 (MVP)

• 오탐 판별: telegram_fp_candidates 는 후보를 좁혀줄 뿐, "대형주를 약칭으로 부른 것"과 "일반명사 충돌"을 자동 구분하진 못한다. 최종 판단은 사람.

• 별칭 재현율: 코드 없이 쓰인 별칭(현대차 단독)은 누군가 현대차(005380) 형태로 쓸 때 비로소 후보로 잡힌다. 볼륨 누적형.

• 수집 트리거: 현재 telegram_sync 수동 호출. 백그라운드 주기 sync 는 추후.

종목 사전 갱신

telegramlens-refresh-stocks   # KRX 상장종목 최신화