` links) |
| `get_new_messages` | Only posts newer than an id — follow a channel over time |
| `analyze_channel` | Stats: top posts, activity, hours, hashtags, words, reactions, sentiment |
| `compare_channels` | Side-by-side: subscribers, posts/day, avg views, engagement rate |
| `export_messages` | Save posts to a local `.json/.csv/.xlsx/.db/.md` file |
Plus prompts `summarize_channel` and `track_topic`, and the resource `telegram://channel/{channel}`.
### Connect it
The only requirement is [uv](https://docs.astral.sh/uv/) (`pip install uv`) — `uvx` downloads and runs the server
on demand. Or `pip install "telegram-channel-scraper[mcp]"` and use `"command": "tgscraper-mcp"` with no args.
Claude Code
```bash
claude mcp add telegram-scraper -- uvx --from "telegram-channel-scraper[mcp]" tgscraper-mcp
```
Inside this repository it is automatic: [`.mcp.json`](https://github.com/specialteam/TelegramScraper/blob/main/.mcp.json) registers the server and
[`.claude/skills/telegram-scraper`](https://github.com/specialteam/TelegramScraper/blob/main/.claude/skills/telegram-scraper/SKILL.md) loads the skill.
Claude Desktop · Cursor · Windsurf · any JSON-configured client
Add to `claude_desktop_config.json` (Settings → Developer → Edit config), `~/.cursor/mcp.json`,
or `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"telegram-scraper": {
"command": "uvx",
"args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"],
"env": { "TGSCRAPER_PROXY": "" }
}
}
}
```
VS Code (Copilot agent mode)
`.vscode/mcp.json`:
```json
{
"servers": {
"telegram-scraper": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"]
}
}
}
```
Remote / HTTP (ChatGPT connectors, n8n, other hosts)
```bash
tgscraper mcp --transport streamable-http # serves MCP over HTTP
```
Environment variables: `TGSCRAPER_PROXY` (proxy URL for all requests), `TGSCRAPER_MCP_MAX_LIMIT` (default 500).
### Claude Skill
[`.claude/skills/telegram-scraper/SKILL.md`](https://github.com/specialteam/TelegramScraper/blob/main/.claude/skills/telegram-scraper/SKILL.md) teaches an agent when and how
to use the CLI (commands, JSON schema, how to cite results). Install it for all your projects:
```bash
mkdir -p ~/.claude/skills && cp -r .claude/skills/telegram-scraper ~/.claude/skills/
```
For claude.ai, zip the `telegram-scraper` folder and upload it under **Settings → Capabilities → Skills**.
**Try asking:**
- *"What are the 5 most viewed posts on @durov this year?"*
- *"Compare the engagement of these three crypto channels: …"*
- *"Search @xyz for 'airdrop' and give me the dates and links."*
- *"Export the last 1000 posts of t.me/abc to Excel."*
Other agents: [`AGENTS.md`](https://github.com/specialteam/TelegramScraper/blob/main/AGENTS.md) and [`llms.txt`](https://github.com/specialteam/TelegramScraper/blob/main/llms.txt) describe the project for LLMs.
---
## 🖥 Web dashboard
```bash
pip install "telegram-channel-scraper[dashboard]"
tgscraper dashboard # → http://localhost:8501
```
Channel metrics, posts table with links, activity/views charts, top words & hashtags, CSV/JSON/Markdown download.
## 🐳 Docker
```bash
docker build -t tgscraper .
docker run --rm -v "$PWD/data:/data" tgscraper durov -n 100 -o durov.csv
docker compose up dashboard # dashboard on :8501
docker compose --profile watch up -d watch # 24/7 monitor archiving to data/archive.db
```
---
## ❓ FAQ
**Does it need a Telegram account or API key?** No. It reads the same public page you see at `https://t.me/s/durov`.
**Which channels work?** Public channels with web preview enabled. Private channels, groups, DMs and bots don't have a
public preview — use [Telethon](https://github.com/LonamiWebs/Telethon) for those.
**`ChannelNotFound`?** The name is wrong, the channel is private, or its owner disabled the web preview.
**Getting HTTP 429 / blocked?** The scraper already retries with backoff. Increase `delay`, lower concurrency, or
rotate proxies (`-p` multiple times). In regions where Telegram is filtered, use `-p socks5://…`.
**Can I get comments / member lists?** No — they are not part of the public preview.
**How accurate is sentiment?** It's a small English/Persian word list: good for trends, not for single posts.
## 🧑💻 Development
```bash
pip install -e ".[dev]"
pytest -q # offline tests with HTML fixtures, no network needed
```
Project layout:
```
tgscraper/
client.py Scraper / AsyncScraper: paging, retries, proxies
parser.py t.me/s HTML → Message / Channel
models.py Message, Media, Channel dataclasses
filters.py MessageFilter
exporters.py json, jsonl, csv, xlsx, sqlite, md
analytics.py summarize(), sentiment()
monitor.py watch() + webhook / Telegram bot notifiers
media.py download_media()
state.py incremental state
cli.py `tgscraper` command
mcp_server.py `tgscraper-mcp` MCP server
dashboard.py Streamlit app
```
The old `from telegram_scraper import TelegramScraper` API still works.
## ⚖️ Responsible use
Only public data is accessed. Respect Telegram's Terms of Service, local laws and people's privacy; keep request
rates reasonable. This project is not affiliated with Telegram.
---
## 🇮🇷 راهنمای فارسی
**Telegram Scraper** ابزاری برای خواندن، جستوجو، مانیتور و تحلیل **کانالهای عمومی تلگرام** است؛ بدون API،
بدون لاگین و بدون شماره تلفن.
### نصب
```bash
pip install "telegram-channel-scraper[all]"
```
### مهمترین دستورها
```bash
tgscraper durov # ۲۰ پست آخر
tgscraper durov -n 500 -o durov.xlsx # ذخیره در اکسل (یا csv / json / db / md)
tgscraper durov --since 2026-01-01 -k بیتکوین
tgscraper search durov "privacy" # جستوجو در کل تاریخچه
tgscraper info durov # اطلاعات و تعداد اعضای کانال
tgscraper stats durov -n 300 # آمار: پربازدیدها، ساعتهای فعالیت، هشتگها، احساسات
tgscraper media durov -d ./media # دانلود عکس و ویدیو
tgscraper watch durov --bot-token TOKEN --chat-id ID # اعلان پست جدید با ربات تلگرام
tgscraper durov -p socks5://127.0.0.1:1080 # استفاده از پراکسی
tgscraper dashboard # داشبورد وب
```
### پایتون
```python
import tgscraper as tg
posts = tg.scrape("durov", limit=100, since="2026-01-01")
tg.export(posts, "posts.csv")
print(tg.format_summary(tg.summarize(posts)))
```
### اتصال به هوش مصنوعی
- **MCP:** با تنظیمات بخش [AI / MCP](#-use-it-from-ai-assistants-mcp--skill) به Claude، Cursor، VS Code و … وصل
کنید. بعد کافی است بپرسید: «پربازدیدترین پستهای این هفتهی @durov چی بوده؟»
- **Skill:** پوشهی `.claude/skills/telegram-scraper` را در `~/.claude/skills/` کپی کنید.
- خروجی همهی دستورها با `--json` برای ایجنتها و اسکریپتها قابل خواندن است.
فقط کانالهایی که پیشنمایش وب (`t.me/s/...`) دارند پشتیبانی میشوند. در ایران برای دسترسی از پراکسی استفاده کنید.
---
MIT License · If this project helps you, give it a ⭐
Keywords: telegram scraper, telegram channel scraper, scrape telegram without api, t.me scraper, telegram
crawler, telegram osint, telegram to csv, telegram to excel, telegram monitor, telegram mcp server, mcp telegram,
claude telegram, ai agent telegram tool, python telegram scraper, اسکرپر تلگرام, استخراج پیام کانال تلگرام