Skip to main content
Glama
letopis-mcp

letopis-mcp

by Toligrim

📜 Летопись (Letopis)

Telegram 채팅 내역의 아카이브 및 스마트 검색 엔진

JSONL 원본 메시지 · 러시아어 형태소를 이해하는 전문 텍스트 검색 · 다운로더 및 매니저

Python 3.10+ Telethon SQLite FTS5 License


아이디어

Letopis는 봇이나 서비스가 아니라 CLI 도구입니다. LLM 에이전트(특히 Claude Code)가 Telegram 채팅 내역을 읽고, 일반적인 지식 베이스처럼 그 내용으로 질문에 답할 수 있도록 설계되었습니다.

아카이브는 일반 파일 — .jsonl로 저장됩니다. 채팅과 월별로 하나씩, append-only입니다. 그 위에 SQLite FTS5 전문(full-text) 검색 인덱스가 구성되며, 이 인덱스는 러시아어 형태를 인식합니다. «хостинг»: 라는 검색어로 «хостиHGOM»라는 단어를 포함한 메시지를 찾아냅니다. 음성 메시지의 텍스트, 파일 이름, 투표 텍스트도 검색에 연결됩니다.

$ ./tg search переезд хостинг --chat devops --from 2025-06

엔진과 데이터는 분리됩니다. 이 저장소에는 코드만 들어 있습니다. 채팅 아카이브 자체, config.toml, .env 및 Telegram 세션은 별도의 분리된 비공개 저장소에 있으며, 무엇을 공개하고 무엇을 공개하지 않을지는 직접 통제할 수 있습니다. 자세한 내용은 «구조» 섹션을 참조하세요.


Related MCP server: telegram-user-mcp

✨ 기능

🔎 전문 텍스트 검색

SQLite FTS5 + pymorphy3: 정확한 단어뿐만 아니라 주요 방식(lemma) 기준으로 검색합니다.

📦 파일 형태의 아카이브

archive/<chat_id>/<YYYY-MM>.jsonl, append-only, 기존 내용은 절대로 변경되지 않습니다.

⬇️ 다운로더 및 매니저

download / sync는 새내용만 받습니다; manifest.json이 추적 항목을 기억합니다.

⭐ 음성 메시지 텍스트 변환

로컬(faster-whisper), Telegram Premium 또는 OpenAI Whisper API 사용

🌐 웹 뷰어

채팅 → 토픽 칩, 무한 스크롤, 필터, 오디오 플레이어, 답글 이동

⌨️ TUI 뷰어

터미널에서 동일한 기능 (textual)

👥 다중 계정

다른 채팅을 다른 Telegram 계정으로 다운로드 가능

🤖 에이전트에 최적화

JSON 출력, 간략한 단락 형식, 안정적인 CLI 계약


🚀 빠른 시작

git clone https://github.com/Toligrim/letopis.git
cd letopis
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/pip install faster-whisper   # опционально: локальная транскрипция голосовых

Letopis는 엔진만 제공합니다. 특정한 아카이브에 연결하려면 **별도의 데이터 저장소(repository)**를 만들고 거기에 ./tg 래퍼를 넣으세요:

#!/bin/sh
exec "$HOME/projects/letopis/.venv/bin/tg" "$@"

이후 모든 것은 데이터 저장소의 루트에서 실행됩니다:

chmod +x tg
./tg login              # авторизация Telegram-сессии (телефон / код / 2FA)
./tg download --chat mychat --media all
./tg index && ./tg meta
./tg search привет

엔진은 데이터 루트를 자동으로 찾습니다. tg를 실행하면 현재 디렉터리에서 위로 올라가며, config.toml과 archive/를 동시에 포함한 폴더를 찾습니다. (또는 환경 변수 TG_ROOT로 신명하게 지정할 수 있습니다.)

🤖 Read-only MCP for ChatGPT

Letopis는 ChatGPT용 read-only MCP retrieval gateway로 작동할 수 있습니다. 서버는 일반 검색과 같은 data/index.db를 사용하지만, 오직 안전한 retrieval 관련 도구 — 아카이브 목록 검색, 검색, 집계, 메시지 선택, 로컬 컨텍스트만 제공합니다. MCP 프로세스는 Telegram 동기화, 파일 다운로드, 색인 수정을 하지 않습니다.

설치 및 실행

MCP SDK와 테스트 의존성을 엔진 환경에 설치하세요:

.venv/bin/pip install -e ".[mcp,test]"

엔트리포인트를 통해 실행합니다:

.venv/bin/letopis-mcp

대안: .venv/bin/python -m tgarchive.mcp.server. 기본적으로 서버는 http://127.0.0.1:8765/mcp를 수신하고 루프백 주소만 허용합니다. 프로덕션에서는 프로세스 환경에 안정적인 커서 시크릿과 인덱스 경로를 지정해야 합니다. 예를 들어:

export LETOPIS_MCP_DB=/srv/letopis-data/data/index.db
export LETOPIS_MCP_CURSOR_SECRET='случайный-длинный-секрет'
.venv/bin/letopis-mcp

환경 변수

변수

기본값

설명

LETOPIS_MCP_DB

config.toml의 [general].db 값, 일반적으로 data/index.db

SQLite 인덱스 경로; 상대 경로는 프로젝트 루트 기준입니다.

LETOPIS_MCP_CURSOR_SECRET

없음; 임시 랜덤 시크릿

HMAC-SHA256 기반 불투명 커서. 프로덕션에서 필수: 없으면 커서가 프로세스 재시작을 넘지 못합니다.

LETOPIS_MCP_HOST

127.0.0.1

루프백 바인드 주소; 앱은 로컬이 아닌 주소를 거부합니다.

LETOPIS_MCP_PORT

8765

Streamable HTTP 엔드 포인트의 TCP 포트.

LETOPIS_MCP_LOG_LEVEL

INFO

구조화된로그 수준 (DEBUG, INFO, WARNING, ERROR, CRITICAL).

LETOPIS_MCP_MAX_CONCURRENCY

8

read-only DB의 최대 동시 작업 개수.

LETOPIS_MCP_QUERY_TIMEOUT_SECONDS

30.0

SQLite 쿼리 및 동시성 슬롯 대기 한계 제한.

LETOPIS_MCP_ROLLING_CALLS_MAX

60

전역 롤링 창에서 완료된 호출 전체 개수 한도.

LETOPIS_MCP_ROLLING_CHARS_MAX

250000

같은 창에서 반환된 전체 문자 수 한도.

LETOPIS_MCP_ROLLING_WINDOW_SECONDS

600

롤링 창의 길이(초).를 나타냅니다.

속도 제한은 의도적으로 프로세스 단위 전역입니다. v1에는 OAuth나 식별된 principals가 없으므로 per-user ACL이 아닙니다. MCP는 이 변수를 프로세스 구성으로 읽고 .env를 자동으로 로드하지 않습니다.

ChatGPT에 연결

권장 구성을 사용하면 Letopis를 인터넷에 직접 노출하지 않습니다:

ChatGPT ↔ OpenAI Secure MCP Tunnel ↔ tunnel-client на этом хосте
                                      ↔ 127.0.0.1:8765/mcp

구체적인 명령과 Secure MCP Tunnel 설정 방법은 현재 OpenA workspace 및 최신 OpenAI 문서에 따라 달라집니다. 접속 시점에 확인하세요. 이 저장소는 확인되지 않은 OAuth/tunnel 명령을 추측하여 만들지 않습니다.

배포 보안

MCP 프로세스에는 data/index.db와 필수 SQLite sidecar 파일 data/index.db-wal / data/index.db-shm만 필요합니다. 그 프로세스에는 .env, telegram.session*, archive/, 미디어 또는 manifest 파일에 접근 권한이 없어야 합니다. 서버를 별도의 Unix 사용자로 최소 권한으로 실행하고, 동기화와 인덱스화는 별도의 프로세스가 쓰기 권한으로 수행해야 합니다.


🗂 구조

репозиторий с данными/
├── config.toml              # настройки: аккаунты, транскрипция, веб-порт
├── .env                     # api_id / api_hash Telegram
├── telegram.session         # сессия аккаунта (и доп. сессии из [accounts])
├── tg -> letopis/.venv/bin/tg   # обёртка-энтрипоинт
├── data/
│   └── index.db             # SQLite + FTS5 — производный, пересобирается
└── archive/
    ├── manifest.json        # какие чаты отслеживаем, каким аккаунтом, какие медиа качаем
    └── <chat_id>/
        ├── 2025-06.jsonl    # сырые сообщения этого месяца — источник истины
        ├── 2025-07.jsonl
        ├── transcripts.jsonl   # расшифровки голосовых/кружков
        ├── media_index.jsonl   # реестр скачанных файлов
        └── media/               # сами файлы
  • JSONL 데이터 — 진실의 근원. 파일은 월별로; sync는 새 메시지만 추가하고 기존 내용은 절대 수정하지 않습니다.

  • index.db — 보조 계층. 언제든 삭제하고 재구성할 수 있습니다 (./tg index --rebuild), 데이터 손실 없이 항상 재현 가능합니다.

  • manifest.json — 매니저. 인덱스 재구성 후에도 유지됩니다. 추적 중인 채팅/토픽과 해당 미디어 다운로드 설정을 저장합니다.

이러한 분리(엔진은 git 저장소로 공개 · 데이터는 별도의 비공개)를 통해 대화 기록 누출의 위험 없이 코드를 자유롭게 개발하고 공유할 수 있습니다.


🧭 명령어

검색 — 주요 기능

명령어

설명

tg search <шлюз…>

전문 텍스트 검색. 플래그: --any (OR 대신 AND), --chat, --topic, --sender, --from / --to, --media, --around N (발견 주변을 위한 컨텍스트), --count, --by-chat / --by-topic / --by-sender (집계), --rank (연관성 기준), --json, --short N, --limit N|0

tg dump --chat X [--topic N]

채팅을 연대순으로 전체 덤프

tg context --chat X --id N

중점 메시지 주변 (기본) 앞뒤 메시지 (--before / --after / --whole-chat)

tg chats

아카이브 채팅 조회

t topics --chat topics — chat X

포럼 채팅의 토픽

tg status

아카이브와 인덱스 상태

Viewer — 수동 모드

명령어

기능

tg web

로컬 웹 인터페이스: 채팅 → 토픽 칩, 무한 스크롤, 필터가 있는 검색, 날짜로 이동, 작성자 필터(닉네임 클릭), 인라인 사진/동영상, 텍스트 변환이 있는 음성 플레이어, 스레드로 이동하는 답글, t.me 링크. 포트는 config.toml [web]에 있음

tg tui

터미널에서도 동일: / 검색 · g 날짜 · s 작성자 · o/n 이전/이후 · c 컨텍스트 · m Telegram에서 열기 · f 파일 열기 · Esc 뒤로 · q 종료

다운로더 및 관리자

명령어

기능

tg dialogs

계정의 모든 채팅(✓ — 이미 아카이브에 있음)

tg download --chat <имя|id|@user>

채팅/토픽을 다운로드하고 추적을 설정합니다. 플래그: --topic N, --from 2025-01, --media photo,voice|all|none

tg sync [--chat X]

추적 중인 모든 채팅의 새 메시지를 추가 다운로드합니다.

tg media --chat X --media voice

이미 다운로드된 파일을 추가 다운로드합니다.

tg transcribe [--provider …]

음성 메시지를 텍스트로 변환해 검색에도 포함되게 합니다.

tg untrack --chat X

채팅 추적을 해제합니다(파일은 디스크에 남습니다).

tg meta / tg index

채팅 이름 업데이트 / 아카이브 추가 인덱싱

tg login [--account имя]

Telegram 세션을 인증합니다(전화 / 코드 / 2FA).

채팅은 id, config.toml의 별칭, 이름의 일부, @username 또는 t.me/... 링크로 지정할 수 있습니다. 새 메시지는 모든 반응, 투표, 서비스 이벤트와 함께 다운로드됩니다.


🎙 음성 메시지 텍스트 변환

제공자는 config.toml [transcription]에서 설정합니다:

제공자

가격

요구 사항

whisper-local

무료, 로컬

faster-whisper, 기본값(모델 small)

telegram

무료

계정의 Telegram Premium

openai

유료(Whisper API)

.env의 OPENAI_API_KEY


👥 여러 계정

[accounts]
default = "telegram.session"
backup  = "sessions/backup.session"

tg login --account backup는 새 세션을 인증합니다. download / sync / dialogs / meta에는 --account 플래그가 있습니다. 매니페스트의 각 채팅은 해당 계정에 귀속됩니다.


🗺 상태

단계

상태

기능

A

✅ 완료

인덱스, 검색, CLI, Claude Code 연동

B

✅ 완료

다운로더 (download/sync, append-only), 설정에 따른 미디어, 백필, 텍스트 변환, 매니저 (manifest.json), 여러 계정, FloodWait 보호

C

✅ 완료

뷰어: tg web (브라우저, 미디어) 및 tg tui (터미널)

다음: 일정에 따른 자동 동기화, 이미지 OCR, Azure Speech 제공자, 선택 항목 내보내기.


🔒 보안

telegram.session과 .env는 Telegram 계정에 대한 완전한 접근 권한을 제공합니다. 이 파일들을 별도의 비공개 리포지토리에 데이터와 함께 보관하고, 이곳에 커밋하거나 어디에도 공개하지 마십시오.


대화를 기억하는 비밀보다 더 잘 기억하도록 만들어졌습니다.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that connects to Telegram as your real user account and exposes read-only tools to read and search messages, list chats and folders, inspect group info, and download media.
      25 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first, read-only MCP server for searching and retrieving cited evidence from archived Telegram chats, including transcripts and media metadata.
      5
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets AI agents search and read your personal Telegram and WhatsApp conversations through a self-hosted, read-only MCP server backed by a single SQLite file.
      2
      AGPL 3.0