<div align="center">

📡 Telegram Scraper

Scrape, search, monitor and analyze any public Telegram channel — no API key, no login, no phone number.

Python library · CLI · MCP server for AI agents · Claude Skill · Web dashboard · Docker

Quick start · CLI · Python · AI / MCP · Dashboard · فارسی

</div>

pip install "telegram-channel-scraper[all]"
tgscraper durov

That's it — the latest posts of t.me/durov, in your terminal.

---

✨ Features

| | | |---|---| | 🔓 Zero setup | Uses the public web preview t.me/s/<channel>. No api_id, no session files, no account ban risk. | | 🧾 Rich data | id, date, text, HTML, views, reactions, author, edited, forwards, replies, photos, videos, voice, documents, link previews, hashtags, mentions, links. | | 🔎 Search & filters | Telegram's server-side search, date ranges, keywords, regex, hashtags, media type, minimum views. | | 💾 Export anywhere | JSON, JSON Lines, CSV (Excel-friendly UTF-8), Excel .xlsx, SQLite (upsert archive), Markdown. | | ⚡ Fast & robust | Async + concurrent multi-channel scraping, retries with backoff, Retry-After handling, rate limiting, rotating HTTP/SOCKS proxies. | | 🔁 Incremental | Remembers the last post per channel — the next run fetches only new posts. | | 👀 Monitor | Watch channels and push new posts to a webhook (Slack, Discord, n8n…) or a Telegram bot. | | 🖼 Media download | Save photos, videos and voice notes of any post. | | 📊 Analytics | Top posts, posting frequency by day/hour/weekday, hashtags, top words, reactions, EN/FA sentiment. | | 🤖 AI-native | MCP server with 8 tools, a ready-made Claude Skill, and --json output for every command. | | 🖥 Dashboard | Streamlit UI with charts and one-click export. | | 🐳 Docker | Run the CLI, the dashboard or a 24/7 monitor in a container. |

---

🚀 Quick start

Install

# everything (CLI + Excel + MCP server + dashboard)
pip install "telegram-channel-scraper[all]"

# or minimal (CLI + library only: httpx + beautifulsoup4)
pip install telegram-channel-scraper

# or from a clone
git clone https://github.com/specialteam/TelegramScraper && cd TelegramScraper && pip install -e ".[all]"

Three ways to use it

tgscraper durov -n 100 -o durov.csv       # 1. command line

import tgscraper as tg                      # 2. Python
posts = tg.scrape("durov", limit=100)

"What did @durov post this week?"           # 3. ask your AI assistant (MCP / Skill)

---

💻 Command line

Anything that looks like a channel works: durov, @durov, t.me/durov, https://t.me/s/durov.

tgscraper durov                                  # latest 20 posts, pretty output
tgscraper durov -n 500 -o durov.xlsx             # save (.json .jsonl .csv .xlsx .db .md)
tgscraper durov -n 0 -o full_history.db          # the whole channel history (-n 0 = no limit)
tgscraper durov telegram tginfo -n 50 -o all.db  # several channels into one SQLite file

tgscraper durov --since 2026-01-01 --until 2026-01-31
tgscraper durov -n 300 -k ton -k bitcoin         # keyword filter (any of them)
tgscraper durov --regex "v\d+\.\d+"              # regex filter
tgscraper durov --hashtag news --min-views 50000
tgscraper durov --media-only --media-type video

tgscraper search durov "privacy" -n 30           # Telegram's own full-history search
tgscraper info durov                             # title, description, subscribers, counters
tgscraper stats durov -n 300                     # analytics report (or: tgscraper stats durov.json)
tgscraper media durov -n 50 -d ./media           # download photos & videos
tgscraper durov --incremental -o archive.db      # only posts newer than the last run

tgscraper watch durov telegram -i 120                                  # print new posts live
tgscraper watch durov --webhook https://hooks.slack.com/services/...  # push to a webhook
tgscraper watch durov -k airdrop --bot-token 123:ABC --chat-id 42     # alert via your Telegram bot

tgscraper durov --json | jq '.[] | {url, views}' # machine-readable output for scripts & agents
tgscraper durov -p socks5://127.0.0.1:1080       # proxy (repeat -p to rotate several)

<details> <summary><b>Example: <code>tgscraper stats</code> (illustrative output)</b></summary>

📊 300 messages from durov
   2025-03-02T10:14:00+00:00  →  2026-09-20T16:40:00+00:00  (1.3 posts/day)
👁  total views 412,905,120 · average 1,376,350
📎 with media 121 {'photo': 88, 'video': 33} · forwarded 4
🙂 sentiment avg +0.21 (+97 / =180 / -23)

🔥 Top posts:
   4,812,000  https://t.me/durov/301  'Telegram now has ...'
...
🕒 Posts by hour (UTC):
   14 ██████████████ 41
   15 ██████████████████████████████ 87

</details>

Run tgscraper --help or tgscraper <command> --help for every option.

---

🐍 Python library

import tgscraper as tg

# Channel info
info = tg.channel_info("durov")
print(info.title, info.subscribers, info.description)

# Latest posts — list of Message objects, newest first
posts = tg.scrape("durov", limit=100)
for p in posts:
    print(p.date, p.views, p.url, p.text[:80], p.media_types, p.reactions)

# Filters (all optional, combine freely)
posts = tg.scrape(
    "durov", limit=None,              # None = whole history
    since="2026-01-01", until="2026-06-30",
    keywords=["ton", "wallet"], regex=r"\bv\d+", hashtag="update",
    media_only=True, media_types=["photo"], min_views=100_000,
)

tg.search("durov", "privacy", limit=20)          # Telegram server-side search
tg.get_message("durov", 123)                     # one post
tg.scrape("durov", incremental=True)             # only new posts since last incremental call

# Many channels concurrently
results = tg.scrape_many(["durov", "telegram", "tginfo"], limit=200)   # {channel: [Message] | Exception}

# Export / load
tg.export(posts, "posts.xlsx")                   # .json .jsonl .csv .xlsx .db .md
posts = tg.load("posts.json")                    # from .json .jsonl .db

# Analytics
stats = tg.summarize(posts)                      # JSON-friendly dict
print(tg.format_summary(stats))
tg.sentiment("Great news, bullish!")             # -1 .. 1 (EN + FA lexicon)

# Media
tg.download_media(posts, "media/", types=["photo", "video"])

# Monitor forever
tg.watch(["durov"], [tg.webhook_notifier("https://example.com/hook"), print], interval=60)

<details> <summary><b>Advanced: reusable / async clients, proxies, streaming</b></summary>

from tgscraper import Scraper, AsyncScraper, MessageFilter

with Scraper(proxies=["socks5://p1:1080", "http://p2:8080"], timeout=20, retries=3, delay=0.5) as s:
    for msg in s.iter_messages("durov", limit=None, filter=MessageFilter(since="2026-01-01")):
        print(msg.id)                     # streams page by page, low memory

async with AsyncScraper(concurrency=10) as s:
    posts = await s.get_messages("durov", 1000)
    async for msg in s.iter_messages("telegram", 50, query="stories"):
        ...

</details>

Message fields

{
  "id": 123, "channel": "durov", "url": "https://t.me/durov/123",
  "date": "2026-01-10T09:30:00+00:00", "text": "…", "html": "…",
  "views": 1250000, "author": null, "edited": false,
  "forwarded_from": null, "reply_to": 120,
  "media": [{"type": "photo", "url": "https://cdn4.telesco.pe/…jpg", "thumbnail": "…", "duration": null, "title": null}],
  "reactions": {"👍": 15000, "🔥": 3200},
  "hashtags": ["news"], "mentions": ["telegram"], "links": ["https://telegram.org/blog"]
}

Media types: photo, video, round_video, voice, audio, document, sticker, link_preview.

---

🤖 Use it from AI assistants (MCP + Skill)

Telegram Scraper ships an MCP server, so Claude, Cursor, VS Code Copilot, Windsurf, ChatGPT and any MCP client can read Telegram channels for you.

flowchart LR
    U["You: 'Summarize @durov this week'"] --> AI[AI assistant]
    AI -- MCP tools --> S[tgscraper-mcp]
    S -- HTTPS --> T["t.me/s/durov"]
    S -- JSON --> AI --> A[Answer with links & stats]

MCP tools

| Tool | What it does | |---|---| | get_channel_info | Title, description, subscribers, photo, media counters | | get_messages | Latest posts with filters (dates, keywords, hashtag, media, views, paging with before_id) | | search_messages | Full-history search inside a channel | | get_message | One post by id (for t.me/<channel>/<id> 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 (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.

<details open> <summary><b>Claude Code</b></summary>

claude mcp add telegram-scraper -- uvx --from "telegram-channel-scraper[mcp]" tgscraper-mcp

Inside this repository it is automatic: .mcp.json registers the server and .claude/skills/telegram-scraper loads the skill.

</details> <details> <summary><b>Claude Desktop</b> · <b>Cursor</b> · <b>Windsurf</b> · any JSON-configured client</summary>

Add to claude_desktop_config.json (Settings → Developer → Edit config), ~/.cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "telegram-scraper": {
      "command": "uvx",
      "args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"],
      "env": { "TGSCRAPER_PROXY": "" }
    }
  }
}

</details> <details> <summary><b>VS Code (Copilot agent mode)</b></summary>

.vscode/mcp.json:

{
  "servers": {
    "telegram-scraper": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"]
    }
  }
}

</details> <details> <summary><b>Remote / HTTP (ChatGPT connectors, n8n, other hosts)</b></summary>

tgscraper mcp --transport streamable-http     # serves MCP over HTTP

</details>

Environment variables: TGSCRAPER_PROXY (proxy URL for all requests), TGSCRAPER_MCP_MAX_LIMIT (default 500).

Claude Skill

.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:

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 da