Skip to main content
Glama
deenesjakoruzh
Toligrim

letopis-mcp

by Toligrim
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

Telegram 聊天记录归档与智能搜索的引擎

原始消息存为 JSONL · 支持俄语词形的全文搜索 · 带管理器的下载器

Python 3.10+ Telethon SQLite FTS5 License

理念

Letopis 不是 bot 也不是 service，而是一个 CLI-инструмент，它专为 LLM-агент（尤其是 Claude Code）能够读取您的 Telegram 聊天历史，并像使用普通知识库一样对它提问。

Первое: 归档以普通文件形式保存 — .jsonl，每个聊天、每月一个、append-only。MySQL 在此基础上构建了可全文检索（FTS5）的 SQLite 索引，它能理解俄语词形：例如查询 «хостинг» 也能命中包含词形«хостингами» 的消息。此外，索引还收入了语音消息的转写、文件名和投票文本。

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

引擎与数据分离。 本仓库只包含代码；聊天记录本身、config.toml、.env 和 Telegram 会话均存放在另一个独立私有仓库中，由你自行决定哪些内容公开、哪些内容不公开。详见«结构»。

Related MCP server: telegram-user-mcp

✨ 功能特性

🔎 全文搜索

SQLite FTS5 + pymorphy3：按词而不是按精确词形搜索

📦 People 归档即文件

archive/<chat_id>/<YYYY-MM>.jsonl，append-only，不重写历史数据

⬇️ 带管理器的下载

download / sync 只拉取新内容；manifest.json 会记住当前跟踪状态

🎙️ 语音转写

本地（faster-whisper）、Telegram Premium 或 OpenAI Whisper API

🌐 Web 查看器

聊天 → 主题 chips、无限滚动、过滤器、语音播放器、按回复跳转

⌨️ TUI 查看器

同样功能但运行在终端中（textual）

👥 多账号

允许不同的聊天使用不同的 Telegram 账号下载

🤖 面向 Agent 优化

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 是独立引擎。若要接入具体归档，需创建一个独立的数据仓库，并在其目录中放入 ./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 显式指定）。

🤖 只读 MCP （用于 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。默认 MCP 监听于 http://127.0.0.1:8765/mcp，且仅接受 loopback 地址。生产环境下建议在进程积存中配置固定 Cursor 密钥、指定索引路径，例如：

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

绑定 loopback 地址；应用会拒绝非本地地址。

LETOPIS_MCP_PORT

8765

Streamable HTTP 接口的 TCP 端口。

LETOPIS_MCP_LOG_LEVEL

INFO

结构日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）。

LETOPIS_MCP_MAX_CONCURRENCY

60

针对只读数据库的最大并发操作数。

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 或识别到单个用户，因此这并不针对单用户 ACL。MCP 将以上变量读取为进程配置，不会自动加载 .env。

对接 ChatGPT

推荐部署方式并完全不把 Letopis 暴露到公网：

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

具体的命令行配置方式和步骤 Secure MCP Tunnel 取决于当前使用的 OpenAI workspace 及 OpenAI 官方最新文档。建议在完成对应方案之前先向 OpenAI 文档核实；本仓库不会做出凭空的相关的 OAuth/tunnel 驱动命令。

部署安全

MCP 进程仅需要**data/index.db**以及对应的 SQLite sidecar 文件（data/index.db-wal、data/index.db-shm）。.env、telegram.session*、archive/、media 文件和 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 — 数据子层。 任何时刻 data/index.db 均可删除并重建（./tg index --rebuild），且不丢数据。

  • manifest.json — 管理文件。 索引重建后依然保留，记录哪些 聊天/主题 在跟踪，以及为它们下载哪类媒体。

这种拆分（引擎对外开源 · 数据私有独立）让你在持有完全控制的前提下，可以自由开发和公开分享代码、无需担心聊天内容泄露。

🧭 命令

主要面向 Agent 的搜索

命令

作用

tg search <слова…>

全文检索。可选参数：--any（OR 代替 AND）、--chat、--id、--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

显示归档中的所有聊天

tg topics --chat X

列举论坛频道的主题 topics

tg status

显示归档与索引状况

查看器 — 手动模式

命令

作用

tg web

本地 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 账号的 完全访问权限。 请将它们放在单独私有的数据仓库中，不要提交到这个仓库， 也不要发布到任何地方。

专为让智能体比你本人更记得住这些对话而制作。

This server cannot be installed

F
license - not found
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • telegram-user-mcp

    22syn
    A
    license
    Not graded
    quality
    B
    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.
    9
    MIT

  • telegram-notes-mcp

    RaspizDIYs
    A
    license
    A
    quality
    C
    maintenance
    A local MCP server that enables full-text and semantic search over your own Telegram chats using your personal MTProto login, with everything running locally.
    7
    MIT

  • tg-mcp

    s4relok
    A
    license
    Not graded
    quality
    B
    maintenance
    Read-only MCP server for Telegram chats and channels that provides digest summaries, message search, and action items.
    27
    MIT

View all related MCP servers

Related MCP Connectors

  • saagarpatel.dev Portfolio

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

  • LLMemory

    Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only

  • telegram-mcp

    Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Toligrim/Letopis-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server