# telegram-notes-mcp

A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code
(or any MCP client) full-text and semantic search over your own Telegram
chats — via your personal MTProto (Telethon) login. Everything runs on your
machine: your own Telegram session, your own SQLite database, your own
(optional) Ollama server for embeddings. Nothing is sent to a third-party
cloud unless you point it at one yourself.

Ask Claude things like *"what did we decide about the deploy last Tuesday?"*
or *"find that link someone shared about X"* and get an answer grounded in
your actual chat history — not a hallucination.

## What's in here

| Piece | What it does |
|---|---|
| **MCP server** (`src/telegram_notes_mcp/server.py`) | Exposes search tools to Claude Code / any MCP client |
| **Web control panel** (`webui/`) | Local browser UI: status, sync, search, ask-Ollama, chat whitelist editor |
| **Topic analytics** (`analytics.py`) | Clusters conversation into "bursts", extracts links, labels topics via LLM |
| **Voice transcription** (`transcribe.py`) | Transcribes voice/video messages via Telegram's built-in transcription (needs Premium) |
| **Cross-device sharing** (`share.py`) | Export/import the derived analytics layer between your own machines |

Only the MCP server needs to be registered with Claude Code — the rest are
optional local tools you run yourself.

## MCP tools

| Tool | Description |
|---|---|
| `search_messages(query, chat_name?, from_date?, to_date?, limit?)` | Full-text search (SQLite FTS5) |
| `semantic_search(query, chat_name?, limit?)` | Search by meaning via embeddings, with rerank if a whitening index is trained |
| `list_chats()` | Whitelisted chats with message counts and last activity |
| `get_chat_context(chat_name, around_message_id, window?)` | Messages surrounding a specific message — useful to read the thread around a hit |
| `sync_now()` | Force an incremental re-sync of all whitelisted chats |
| `embed_index(batch?)` | Index one batch of messages without embeddings (call repeatedly while `has_more` is true) |
| `transcribe_voices(limit?)` | Transcribe pending voice/video messages (requires Telegram Premium) |

## Quick start — mini-app (Windows)

A standalone local app: control-panel window (no browser chrome) + a **system
tray icon**, with Start Menu / Desktop shortcuts. After cloning:

```powershell
powershell -ExecutionPolicy Bypass -File setup.ps1
```

This creates a venv, installs dependencies (`.[app,analytics]`), makes a
`.env` from the template, and creates shortcuts. Then:

1. Fill in `.env` — your own `TG_API_ID` / `TG_API_HASH` (from
   [my.telegram.org](https://my.telegram.org)) and `TG_CHAT_WHITELIST`.
2. Log in to **your own** Telegram: `.venv\Scripts\python.exe scripts\login.py`
   (creates your local session + database — your chats only).
3. Launch the **telegram-notes** shortcut → a window opens and a tray icon
   appears.

Panel without the tray (plain browser): `.venv\Scripts\python.exe webui\panel.py`.
More detail: [webui/README.md](webui/README.md).

## Quick start — manual / macOS / Linux

1. **Windows only:** if your only Python is the Microsoft Store version
   (`where python` points into `WindowsApps\...`), install a regular
   Python from [python.org](https://www.python.org/downloads/) (or
   `winget install Python.Python.3.13`) and use that one below — the Store
   build has a known bug where the interactive login prompt can crash with
   `EOFError` on a repeated code entry.
2. Create a virtualenv and install the package:
   - Windows: `python -m venv .venv && .venv\Scripts\activate`
   - macOS/Linux: `python3 -m venv .venv && source .venv/bin/activate`
   - Then: `pip install -e ".[dev]"`
3. Create your **own** `api_id`/`api_hash` at
   [my.telegram.org](https://my.telegram.org) → "API development tools" —
   pick any app name, it's free and instant. **Don't reuse someone else's
   `api_id`/`api_hash`** — see
   [docs/prd/001-login-code-never-arrives.md](docs/prd/001-login-code-never-arrives.md)
   for why that silently breaks login codes.
4. Copy `.env.example` to `.env` and fill in `TG_API_ID` / `TG_API_HASH`
   and `TG_CHAT_WHITELIST` (comma-separated usernames like `@someone`
   and/or numeric chat ids like `-1001234567890`; `me` = your own Saved
   Messages).
5. Run the one-time interactive login: `python scripts/login.py`
   (asks for your phone number + the code Telegram sends you — check the
   Telegram app itself first, not just SMS; creates the `.session` file at
   `TG_SESSION_PATH`).
6. Register the server with Claude Code (see below).

Each machine (Windows, macOS, ...) does its own login and keeps its own
local `.session` file and SQLite database — nothing syncs between machines
unless you explicitly use the `share.py` export/import feature.

## Configuration

All configuration lives in `.env` (see `.env.example` for the full list with
comments). Required: `TG_API_ID`, `TG_API_HASH`, `TG_CHAT_WHITELIST`.
Everything else — semantic search (`TG_OLLAMA_URL` / `TG_EMBED_MODEL` /
`TG_OLLAMA_AUTH`), analytics noise-filter (`TG_OWN_BOT_USERNAME`), and the
bot-message editor (`TG_BOT_TOKEN`) — is optional.

## Registering with Claude Code

Preferred: use the CLI so it lands in whichever config file your Claude
Code version actually reads (this has moved between versions — don't
hand-edit `~/.claude/.mcp.json`, it's not necessarily the file `claude mcp
list` uses; check with `claude mcp list` after adding):

```
claude mcp add telegram-notes -- /absolute/path/to/telegram-notes-mcp/.venv/bin/python -m telegram_notes_mcp.server
```

On Windows use the `.venv\Scripts\python.exe` path. A newly added
user-scope server may need a one-time approval — run `claude mcp list` and,
if it shows "Pending approval", approve it via `claude mcp get
telegram-notes` or `/mcp` inside an interactive session.

Don't add a `cwd` field/flag — Claude Code silently ignores it and always
launches the server from wherever Claude Code itself was started, not this
directory. That's fine: `config.py` locates `.env` and resolves any
relative `TG_SESSION_PATH`/`TG_DB_PATH` by the project's own directory
(derived from this package's install location), not the process's current
working directory, so the server works correctly regardless of where the
MCP client actually launches it from.

## Known issues and their fixes

If something doesn't work, check whether it's already documented:
- [docs/prd/001-login-code-never-arrives.md](docs/prd/001-login-code-never-arrives.md) — login code never shows up
- [docs/prd/002-numeric-chat-id-not-resolving.md](docs/prd/002-numeric-chat-id-not-resolving.md) — a group/channel whitelisted by numeric id fails to sync
- [docs/prd/003-claude-code-mcp-registration.md](docs/prd/003-claude-code-mcp-registration.md) — server doesn't show up in Claude Code after registering it

## Running tests

`pytest`

## Privacy

- Your Telegram session (`.session`), database (`messages.db`), and `.env`
  never leave your machine and are git-ignored by default.
- Semantic search and Q&A require an Ollama server — point `TG_OLLAMA_URL`
  at your own (local or self-hosted); no data goes to a third-party LLM API
  unless you configure one yourself.
- Only chats you explicitly list in `TG_CHAT_WHITELIST` are ever synced.

## License

MIT — see [LICENSE](LICENSE).