telegram-mcp
by ZeroMemory
README.md
# Telegram Organizer
Organize Telegram folders and categories through the bundled MCP server, and export your own messages from accessible groups and public spaces into searchable local reports. Scan broadcast channels for your selected reactions and resume from SQLite checkpoints.
The bundled `telegram-mcp/` adapts [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp). It provides folder/category operations, client settings, proxy support and an explicit read-only tool selection.
## Install
Requires Windows and Python 3.12.
```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements-lock.txt
.\.venv\Scripts\python -m pip install --no-deps ./telegram-mcp
```
## Use with an agent
Connect the bundled server to your MCP client using the [server setup](telegram-mcp/README.md#mcp-client-configuration). Configure your Telegram credentials and session once; the client then exposes the server's tools to the agent. For example, ask:
```text
Show my Telegram folders and suggest a clearer grouping for them.
```
Use `TELEGRAM_EXPOSED_TOOLS=read-only` for inspection. Folder and category changes require `TELEGRAM_EXPOSED_TOOLS=all`, which exposes all tools and is the server default. Use the commands below for CLI exports.
## Export your account
Copy `export.env.example` to `.env`. Set your API ID, API hash and authorized StringSession. Group and public exports read `TELEGRAM_SESSION_STRING_SECOND`. The reaction scanner reads `TELEGRAM_SESSION_STRING`.
```powershell
.\.venv\Scripts\python audit/export_second_group_messages.py --env-file .env --output-stem audit/second-account-group-messages
.\.venv\Scripts\python audit/export_second_public_messages.py --env-file .env --output-stem audit/second-account-public-messages
.\.venv\Scripts\python audit/scan_first_account_reactions.py --env-file .env --account-id 123456789 --workers 1
```
Replace `123456789` with your Telegram user ID. The scanner uses an account-specific checkpoint. It can also read the account ID from an existing `my-telegram-group-messages-stats.json`.
To resume a reaction scan, repeat the command with the same SQLite file. Incomplete channels resume from the last offset and completed channels are skipped. Reports include channel status. JSONL preserves original text. CSV escapes spreadsheet formulas.
Transport defaults to direct. Proxy options include `mtproxy`, `socks5`, `socks4` and `http`. To use an existing TG WS Proxy adapter, select `tg-ws-proxy` and set `TELEGRAM_PROXY_CONFIG` explicitly.
## Generate HTML from your exports
```powershell
.\.venv\Scripts\python audit/generate_second_group_messages_html.py --input audit/second-account-group-messages.jsonl --output groups.html
.\.venv\Scripts\python audit/generate_second_public_messages_html.py --input audit/second-account-public-messages.csv --output public.html
```
Each generator updates its default report in `audit/`. Use `--output` for a new destination and add `--overwrite` to replace an existing report.
For saved first-account exports, use `audit/generate_telegram_messages_html.py` with `--input` and `--comments` pointing to your CSV files. Open the reports in a browser to search messages, filter by group, space or type, and follow Telegram links. Groups with the same name remain separate by ID. Open `t.me/c` links with an account that belongs to the group.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues