shadow-tg

Read public Telegram channels from AI agents — no MTProto, no Telethon, no api_id.

Part of the Shadow product line: tools that give AI agents eyes on the open web.

MCP server that scrapes Telegram's public web preview (t.me/s/…): channel metadata, posts, media URLs, comments, and DuckDuckGo-backed channel search. Stack: httpx + lxml + FastMCP. No browser.

get_channel("durov")
# → title, subscribers_raw ("2.54M"), description, avatar…

get_posts("durov", limit=3)
# → recent posts + views_raw + next_before cursor

search_posts("durov", "TON")
# → filter ~100 recent posts client-side (not Telegram search)

Pain point

Agents need Telegram signal (channel size, engagement, fresh posts). Official Bot API can't read arbitrary public channels. MTProto/Telethon means app registration, session files, and ban risk.

shadow-tg stays on the public HTML surface Telegram already exposes. Same data a browser sees — structured for MCP tools.

Related MCP server: tdlib-mcp-server

Quick install

pip install shadow-tg

From source:

git clone https://github.com/ulinycoin/shadow-tg.git
cd shadow-tg
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Cursor

After pip install shadow-tg (or pip install -e . from source), shadow-tg is available as a command:

{
  "mcpServers": {
    "tg": {
      "command": "shadow-tg"
    }
  }
}

Or point to the project venv directly:

{
  "mcpServers": {
    "tg": {
      "command": ".venv/bin/python",
      "args": ["-m", "tg_mcp.server"]
    }
  }
}

Claude Code (Anthropic)

After pip install shadow-tg, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "tg": {
      "command": "shadow-tg"
    }
  }
}

Claude Code also picks up the included CLAUDE.md for project context.

Hermes (config.yaml)

After pip install shadow-tg:

mcp_servers:
  tg:
    command: shadow-tg
    enabled: true

Or module form (pointing to the project venv):

mcp_servers:
  tg:
    command: python3
    args: ["-m", "tg_mcp.server"]
    enabled: true

Example prompts

Copy-paste these into your AI agent's chat after adding shadow-tg as an MCP server:

Find the top 5 Telegram channels about AI agents,
check their size and engagement, and recommend the best one

Read the last 10 posts from @durov and summarize
what he's talking about this week

Inspect these channels for quality: @techcrunch, @techmeme, @verge
Drop any that are stale or have inflated subscribers

Search for Telegram channels about Rust programming.
Verify their subscriber counts and show me the 3 most active ones

Tools

Important response fields

• requested / canonical — alias vs real username from data-post (e.g. @durov stays @durov; alias channels like @some_news → @original_name)

• subscribers / subscribers_raw — int + display string (2.54M). Use raw for size; don't drop the decimal (2.54M ≠ 54M)

• views / views_raw — post views, not channel size

• median_views / engagement_ratio / flags — from inspect_channels / verified search; stale = no posts newer than stale_after_days (default 30)

• engagement_flags / likely_inflated — fake-sub signals: low_engagement, low_ratio, dead_reach

• has_more / next_before — history cursor; next_after — live-tail comments (~3s poll)

Examples (@durov)

resolve_channel("durov")
get_channel("durov")
get_posts("durov", limit=3)
get_post("durov", 513)
get_media("durov", 532)
search_posts("durov", "TON")
inspect_channels("durov, telegram")
search_channels("durov ton", limit=5, verify=true)

Comments (only if the channel has a discussion group):

get_comments("durov", 513)              # first page → next_before + next_after
get_comments("durov", 513, before=…)    # older
get_comments("durov", 513, after=…)     # live-tail; empty = wait, reuse after

Do not pass before and after together.

How data is fetched

Limitations

• Public channels only (web preview). Private / "Contact" pages → exists: false

• No reactions, members list, DMs, or cross-channel user comment history

• search_posts is a recent-post filter, not Telegram full-text search

• search_channels depends on DuckDuckGo indexing

• Comments require a linked discussion group

• CDN media URLs can expire

Layout

src/tg_mcp/
  server.py           # FastMCP tools
  tme_parser.py       # t.me/s posts / channel / media
  comment_parser.py   # discussion widget + loadComments auth
  channel_search.py   # ddgs
  channel_quality.py  # median views + inflation / stale flags
  cache.py            # TTL cache under /tmp/tg-mcp-cache
CLAUDE.md             # Claude Code project context
tests/
  fixtures/           # HTML fixtures

Tests

PYTHONPATH=src python3 -m pytest tests/ -v

License

MIT. Free for anything.

#telegram #mcp #ai-agents #llm-tools #web-scraping #python #channel-analytics #no-mtproto