Telegram Community MCP
Allows searching and syncing messages from Telegram communities, enabling hybrid search over message history with full-text and semantic understanding.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Telegram Community MCP search for discussions about deployment strategy"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Telegram Community MCP
MCP server for hybrid search over Telegram community message history. Connect it to Claude Desktop and search your chats by meaning, not just keywords.
What it does
Hybrid search — combines full-text search (FTS5) with semantic vector search (sentence embeddings), merged via Reciprocal Rank Fusion
MCP integration — Claude Desktop calls search tools directly, reasons over results, and pulls conversation threads for context
Incremental sync — checkpoint-based ingestion, only fetches new messages after initial import
Related MCP server: quarry
How it works
Claude Desktop ←→ MCP Server (stdio) ←→ SQLite (FTS5 + sqlite-vec)
←→ SentenceTransformer (embeddings)
←→ Telegram API (sync)Search modes:
Mode | How it works | Best for |
| SQLite FTS5 with unicode tokenization | Exact word/phrase lookup |
| KNN over 384-dim embeddings ( | Finding messages by meaning, cross-language |
| Both FTS + semantic, merged with RRF (default) | General search — best of both worlds |
The embedding model is multilingual (50+ languages, ~120 MB) and runs on CPU. A query in Russian will find answers written in English and vice versa.
Performance
Tested on a mini PC (Intel N100, 16 GB RAM):
Messages | DB size | FTS speed | Semantic speed | RAM usage |
100K | ~200 MB | < 50 ms | < 500 ms | ~800 MB |
500K | ~1 GB | < 50 ms | ~1 sec | ~1.2 GB |
1M | ~2 GB | < 50 ms | 2–5 sec | ~2 GB |
Semantic search uses a two-phase scheme: a coarse binary (Hamming) KNN over a bit[384] index ~32x smaller than the fp32 vectors, then an exact fp32 rerank of the top candidates. The small binary index stays cache-resident, which keeps the cold first-query latency low (e.g. on 1.5M vectors: cold semantic ~2 s vs ~12 s for a full fp32 scan; warm hybrid ~0.9 s). FTS5 scales to millions without issues. The binary index is built from existing vectors — no re-embedding — via python scripts/ingest.py --build-binary.
Initial ingestion of 120K messages takes ~90 minutes on CPU (embedding generation). Incremental syncs are near-instant.
Quick start
Prerequisites
Python 3.11+
uv package manager
1. Install
git clone https://github.com/nullnumber1/Telegram-Community-MCP.git
cd Telegram-Community-MCP
uv sync2. Get Telegram API credentials
Go to my.telegram.org → API development tools → Create application.
Troubleshooting:
my.telegram.orgoften returns a generic ERROR when creating an app in a regular browser. This is a known issue. Try using a VPN (different regions), an antidetect browser, or a mobile browser. It may take several attempts.
Save your api_id and api_hash.
3. Configure
cp config.env.example config.envEdit config.env:
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
CHAT_IDS=-1001234567890,-1009876543210To find chat IDs, run auth first, then:
make chats4. Authorize
make authScan the QR code with Telegram (Settings → Devices → Link Desktop Device). Session is saved locally — you only need to do this once.
5. Ingest messages
make ingestThis fetches the full history of configured chats and builds the search index. Progress is printed to stdout. Safe to interrupt — resumes from the last checkpoint.
6. Connect to Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"tg-community-search": {
"command": "uv",
"args": ["run", "--project", "/absolute/path/to/Telegram-Community-MCP", "python", "server.py"]
}
}
}Restart Claude Desktop. The search tools should appear in the tools menu.
MCP tools
Tool | Description | Key parameters |
| Search messages across all indexed chats |
|
| Get surrounding thread: messages before/after + replies |
|
| Fetch new messages from Telegram |
|
| Show indexed chats with message counts | — |
| Index statistics: totals, DB size, per-chat breakdown | — |
Project structure
├── server.py # MCP server entry point
├── src/
│ ├── db.py # SQLite: schema, CRUD, FTS5, sqlite-vec queries
│ ├── embedder.py # SentenceTransformer wrapper (lazy-loading)
│ ├── search.py # Hybrid search: FTS + KNN + RRF fusion
│ └── telegram.py # Telethon client wrapper
├── scripts/
│ ├── auth.py # One-time Telegram authorization (QR code)
│ ├── ingest.py # Full import / incremental import
│ ├── list_chats.py # List all account dialogs
│ └── monitor.py # Monitor ingestion progress
├── tests/
│ ├── test_db.py # Database operation tests
│ ├── test_embedder.py # Embedder tests
│ └── test_search.py # Search and RRF fusion tests
├── config.env.example # Configuration template
├── pyproject.toml # Dependencies and tool config
├── Makefile # Dev and deployment shortcuts
└── tg-community-search.service # systemd unit (for server deployment)Deployment (optional)
For running on a remote server (e.g., a mini PC):
Edit
tg-community-search.service— replaceYOUR_USERwith your usernameDeploy:
make deploy REMOTE_HOST=192.168.1.42 REMOTE_USER=myuser REMOTE_PASS=mypassSet up hourly auto-sync via cron on the remote:
crontab -e # Add: 0 * * * * cd /home/myuser/tg-community-search && ~/.local/bin/uv run python scripts/ingest.py >> logs/cron-sync.log 2>&1
Development
make test # Run tests
make lint # Lint and format
make dev # MCP inspector (browser UI for testing tools)License
MIT
Available Tools
5 toolsget_contextB
Get thread context around a message: window messages before/after, plus all replies to the message.
Inputs: message_id (required), window. Returns: result
get_statsA
Index statistics: total messages, per-chat breakdown, DB size.
Inputs: no named parameters. Returns: result
list_chatsA
Show indexed chats: name, ID, message count, last sync date.
Inputs: no named parameters. Returns: result
searchA
Search Telegram community messages.
mode=fts — exact word search (fast).
mode=semantic — meaning-based search (finds similar).
mode=hybrid — both combined with rank fusion (recommended).
chat_id — filter by specific chat.
date_from/date_to — ISO date filter, e.g. "2024-01-01".
Inputs: query (required), mode, limit, chat_id, +2 more. Returns: result
syncA
Sync new messages from Telegram.
Without arguments — all configured chats.
With chat_id — only the specified chat.
Returns the number of added messages.
Inputs: chat_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: sync ingests messages, get_stats reports index metrics, search queries messages, get_context expands a thread, and list_chats enumerates chats. Search and get_context both retrieve messages but are clearly differentiated (query vs. thread expansion around a known message). No meaningful overlap.
Three tools follow a clean verb_noun pattern (get_stats, get_context, list_chats), while sync and search are bare verbs. This is a minor deviation but still readable and consistent in spirit (all lowercase snake_case).
Five tools is well within the ideal 3-15 range and each earns its place in the ingest-search-context lifecycle. Nothing is redundant or superfluous.
The read/index domain is well covered: sync, stats, search, thread context, and chat listing form a coherent lifecycle. Minor gaps exist (no fetch-by-message-ID, no chat add/remove or re-index management), but agents can work around these via search and list_chats.
Related MCP Connectors
Search your knowledge bases from any AI assistant using hybrid RAG.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Your WhatsApp history in Claude and ChatGPT: search years of chats, voice notes transcribed.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Related MCP Servers
- AlicenseAqualityDmaintenanceSemantic search across Claude Code conversations. Hybrid vector + keyword search, fully local, background indexing.628 npm11MIT
- AlicenseAqualityAmaintenanceEnables local semantic search over documents and code for Claude Code and Claude Desktop, running entirely offline with local embeddings and vector storage.14424 PyPI7MIT
- AlicenseAqualityDmaintenanceEnables reading and searching Telegram channel/group/DM messages from Claude Code using MTProto for full message history access.535 npmMIT
- AlicenseBqualityDmaintenanceEnables searching and browsing of Claude conversation history with hybrid search combining full-text, Spotlight, and optional vector embeddings.101MIT