telegramlens-mcp 0.4.4

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

TelegramLens

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

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

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

---

구조

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

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

---

설치 & 로그인

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 툴

조회

툴	용도
telegram_sync(minutes)	최근 메시지 수집·구조화 (먼저 실행)
telegram_trending(hours, top)	기간 내 언급량 상위 종목
telegram_momentum(hours, baseline_hours)	언급 급증 종목 — 새 내러티브 포착
telegram_stock_buzz(query, hours)	특정 종목 언급 요약 + 원문 샘플
telegram_messages(channel, hours)	원문 메시지 drill-down (채널·시간)
telegram_search(query, hours, channel)	원문 키워드 전문검색 — 종목 언급 없는 거시·산업·테마 글까지
telegram_channels()	수집된 채널 목록
telegram_status()	로그인·수집 상태

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

채널 진단

툴	용도
telegram_classify_channels(threshold)	채널별 종목 언급 밀도 리포트(어느 채널이 종목 위주인지 진단 — 수집을 제한하진 않음)

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

툴	용도
telegram_fp_candidates(days)	오탐 후보(일반명사 충돌 의심) 리뷰 리스트
telegram_alias_candidates(days)	누락 별칭 후보(이름(코드) 표기 기반, 고정밀)
telegram_block_name(code)	모호어 차단(이름단독 매칭 차단, 코드 동반 시만 인정)
telegram_add_alias(alias, code)	별칭 등록 (즉시 반영)

---

추출 품질 2층

층	역할	데이터
코드 검증	6자리 코드는 KRX 사전에 있는 것만 채택	KRX 2700+
별칭 (recall↑)	통용어/약어 → 코드 (현대차→005380)	data/aliases.json + 사용자 override
블록리스트 (precision↑)	일반명사 충돌 종목은 코드 동반 시만 (대상, TP)	data/ambiguous_codes.json + override

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

---

알려진 한계 (MVP)

• 오탐 판별: telegram_fp_candidates 는 후보를 좁혀줄 뿐, "대형주를 약칭으로 부른 것"과 "일반명사 충돌"을 자동 구분하진 못한다. 최종 판단은 사람.
• 별칭 재현율: 코드 없이 쓰인 별칭(현대차 단독)은 누군가 현대차(005380) 형태로 쓸 때 비로소 후보로 잡힌다. 볼륨 누적형.
• 수집 트리거: 현재 telegram_sync 수동 호출. 백그라운드 주기 sync 는 추후.

---

종목 사전 갱신

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