1---
2name: telegram-mcp
3description: "Telegram MTProto MCP server with userbot watcher, chat/DM parser, context builders, criminal analysis and personality profiling. Use for reading Telegram messages, parsing chat history, criminal analysis, and psychological profiles."
4---
5 
6# Telegram MCP — Watcher, Parser & Analysis
7 
8Full-featured Telegram MTProto MCP server. Connects to Telegram as a userbot and exposes message reading, sending, and parsing as MCP tools.
9 
10## Features
11 
12- **Userbot watcher** — monitors all messages, triggers AI agent on keyword
13- **Chat/DM parser** — paginated parsing of any chat or DM via `parse_chat.py`
14- **Context builders** — stats, top words, LLM summaries, people profiles
15- **Criminal analysis** — detects CSAM, fraud, NCA violations, hate speech
16- **Personality profiling** — psychological portrait from message history
17 
18## Setup
19 
20```bash
21cp .env.example .env
22# Fill in API_ID, API_HASH, SESSION_NAME, OWNER_ID from https://my.telegram.org/apps
23pip install -r requirements.txt
24python3 session_string_generator.py  # authorize session once
25```
26 
27## Run watcher as systemd service
28 
29```bash
30sudo cp tg-watcher.service /etc/systemd/system/
31sudo systemctl enable --now tg-watcher
32```
33 
34## MCP Tools (via mcporter)
35 
36- `send_message` — send message to chat
37- `reply_to_message` — reply to specific message
38- `iter_all_messages` — paginated message fetch
39- `iter_messages_by_user` — messages from specific user
40- and 90+ more Telegram API methods
41 
42## Important notes
43 
44See `CLAUDE.md` for full list of gotchas. Key ones:
45- Use `\n` not `<br>` in HTML messages
46- `iter_all_messages` for DMs, not `list_messages`
47- Semaphore required for parallel agent calls
48 
49## Source
50 
51GitHub: https://github.com/SkrudjReal/telegram-mcp
52