telegram-notes-mcp

A local MCP 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 -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) 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.

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 (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 → "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 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 — login code never shows up
• 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 — 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.