telegram-private-search

Turn your Telegram history into searchable memory for you and your AI tools.

telegram-private-search is a local-first Kotlin/JVM tool and MCP server that turns years of private Telegram chats into a structured, searchable knowledge source.

It is built for a very specific feeling: you know a conversation happened, you remember what it meant, but you do not remember the exact wording well enough to find it with normal search.

With this project, your assistant can stop guessing and start querying your local Telegram archive directly.

Quick start

cp .env.example .env
./gradlew test
./gradlew run --console=plain --args='index --limit-per-chat 500'
./gradlew run --args='mcp'

Then connect an MCP-compatible client to the server and query your Telegram history in natural language.

Why this is interesting

Your Telegram history often contains:

• decisions that were never written down anywhere else
• informal project updates
• agreements, promises, and follow-ups
• travel plans, addresses, links, and recommendations
• context that only exists inside chat threads

This project turns that messy, memory-shaped information into something an MCP-compatible client can actually use.

Instead of scrolling through years of chats and trying random keywords, you can ask higher-level questions such as:

• "Find the last time we discussed Readian progress"
• "When did she mention sending the invoice?"
• "Show messages where he said he was blocked on the backend"
• "Find the conversation where we compared apartment options"

It indexes your private Telegram chats into a local SQLite database, then combines local keyword search, recency-aware ranking, and thread expansion so vague, memory-shaped queries still have a good chance of finding the right message.

What this MCP server is

This project exposes your Telegram search index through an MCP server over stdio.

That means an AI tool that supports MCP can call into this server as a capability instead of you manually copying text around. In practice, this lets your assistant search your local Telegram history as a structured tool, returning relevant messages and context when you ask questions in natural language.

Think of it as a bridge between:

• your local Telegram archive
• a search engine tuned for conversational recall
• an MCP-compatible assistant or client

Why MCP matters here

Without MCP, this project is already useful as a CLI search tool.

With MCP, it becomes part of a larger assistant workflow. Your client can treat Telegram search as a real tool call instead of a manual side task. That makes it possible to:

• ask questions in natural language and get grounded results
• combine Telegram search with other tools in the same assistant session
• reduce hallucinated memory reconstruction
• keep the message index local while still making it usable by AI tooling

Architecture at a glance

Telegram account
      |
      v
   TDLight client
      |
      v
Message ingestion
      |
      v
Local SQLite index (Room)
      |
      +--> keyword search
      |
      +--> local lexical retrieval
      |
      v
Ranking and result shaping
      |
      +--> CLI search
      |
      +--> MCP server over stdio
              |
              v
      MCP-compatible assistant or client

In short: Telegram messages come in, a local index is built, local retrieval finds relevant results, and the MCP server exposes that capability to tools that can speak MCP.

Why it exists

People rarely remember the exact words used in a chat. They remember intent, context, and fragments:

• "the message where he finally agreed"
• "that t

... View full README on GitHub