Sherlogram
Operates inside a Telegram account to join groups, read and search messages and public posts, look up users and groups, send messages, organize folders, trace supply chains from ads to upstream sources and payment addresses, assess seller legitimacy, maintain shared scam lists, and monitor markets and groups.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Sherlogram
Sherlock for Telegram — a nod to Sherlock: follow one ad to the storefront, the upstream and the payment address.
English · 中文 · Telegram group
Let an AI (Claude, or any MCP-capable assistant) work inside your Telegram account: join groups, read messages, search every public post on Telegram, look people up, run groups, send messages, organize folders — 49 tools, 107 features, one connection shared by every window on your machine.
What makes it different from other Telegram MCP servers: it grew out of tracing supply chains back to their source — one sentence draws the chain, one sentence grades a seller.
One sentence, one supply chain
Tell Claude "read the posts with links in these five groups, follow two hops, where does it come from?" — it calls trace_source once and 50 seconds later hands you this graph (a real run; unrelated branches removed, names masked):
graph LR
classDef seller fill:#f4f4f4,stroke:#999
classDef site fill:#e8f1ff,stroke:#3b82f6
classDef source fill:#ffedd5,stroke:#ea580c,stroke-width:3px
s1["@seller_A"]:::seller
s2["@seller_B"]:::seller
b1["@group_helper_bot"]
w1["uu-**.net<br/>AI video API"]:::source
w2["uu-**.com<br/>video CMS vendor"]:::source
u1["@u***_com<br/>upstream U"]:::source
g1["@u*_cms<br/>U's group"]:::source
c1["@u*_cms_com<br/>U's channel"]
s1 -->|links to| w1
s1 -->|links to| w2
s1 -->|mentions| u1
s2 -->|links to| w1
s2 -->|links to| w2
s2 -->|mentions| u1
s2 -->|mentions| g1
u1 -->|bio says| w1
u1 -->|bio says| w2
c1 -->|links to| w1
c1 -->|mentions| u1
b1 -->|posts in| g1
b1 -->|links to| w1
p1["@wholesale_channel"]:::seller
k1["a***.pro<br/>card shop"]:::site
kf["@a***_kefu<br/>support"]
kg["@a***pro<br/>group"]:::source
p1 -->|links to| k1
k1 -->|contact on site| kf
k1 -->|contact on site| kg
kf -->|bio says| k1
kf -->|mentions| p1
kf -->|mentions| kg
s3["@spam_bot"]:::seller
t1["t***ai.com"]:::site
s3 -->|links to| t1Read 39 posts from 10 sellers, probed 12 sites, re-checked 8 handles. Convergence point: @u***_com (mentioned by 5 accounts).
Read it at a glance: two "sellers" push two sites, and the sites, the bios and the group all point at one upstream U — the sellers are middlemen. The other chain: a channel → its card shop → the support handle the shop lists → whose bio points back at the channel. A closed loop: that one sells its own stock. Orange thick border = where the clues converge; red = flagged as phishing by Cloudflare or flagged by Telegram.
Then say "is @someseller legit?" — it calls check_seller once and ten seconds later you get a card: tier A–D, every red flag with the quote it came from:
{"handle":"@v***bot","tier":"C","tier_definition":"证据不足,或长期沉寂,或商业模式风险高 (thin evidence / dormant / risky business model)",
"red_flags":["活跃度靠刷屏:50 条只有 1 条不同文案(50.0 倍) (activity is spam: 50 posts, 1 distinct text, 50x)"],
"activity":{"posts_sampled":50,"days_since_last":0,"distinct_texts":1,"spam_ratio":50.0,"posts_with_price":50},
"provenance":{"edited_old":0,"forwarded_old":0,"via_bot":0},
"clues":{"domains":["t***ai.com"],"prices":["5 元","98 元","100刀"]},
"sites":{"t***ai.com":{"verdict":"reachable"}},
"accusations":[],"related_accounts":[],"confidence":"medium"}Then ask "where does the money from this payment address go?" — same trace_source, pass address, and it follows the USDT (Tron) transfers two hops down, 14 seconds:
{"summary":"查了 4 个钱包的链上流水。线索汇聚点:TQGB…Zwj2(3 个地址给它打过钱;1 个钱包的钱转到它(资金汇聚);链上进 2288.0万U、出 1265.0万U)",
"wallets":{"TNG3…CkVH":{"in_usdt":719414,"out_usdt":6755927,"payers":155,"payees":24,"first":"2026-08-10","last":"2026-09-09",
"top_out":[{"address":"TQGB…Zwj2","usdt":2879940,"count":2},{"address":"TW3o…oHFp","usdt":1888888,"count":1}],
"note":"只看了最近 200 笔","explorer":"https://tronscan.org/#/address/TNG3…CkVH"}}}Payment addresses found in posts enter the graph automatically: two sellers collecting on the same address are one person — harder evidence than any text clue; whoever the money finally pools at is the upstream.
A storefront domain can be dug into directly: trace_source(site="…", deep_sites=1) fetches its homepage for contacts and APIs, then asks three free public sources what sits behind it — other domains on the same certificate (one owner, one cert), other sites on the same server (looked up by domain on the far side, so a local proxy doesn't matter), and registrar / registration date / registrant / nameservers; sibling sites enter the graph with "same cert", "same server" and "same registrant" edges. A certificate older than the current registration gets flagged "domain changed hands, old reputation doesn't count"; check_seller(deep_sites=True) raises a red flag when a storefront domain was registered less than a month ago.
Don't keep what you found to yourself: scam_list is a shareable scam list. add runs the seller card on a handle and stores tier, red flags, quoted evidence from the groups, payment addresses and storefronts plus your own one-line note as one record; query looks up a handle, numeric id, wallet or domain; merge folds in list files other people send you; export writes the Rose group-bot federation-ban format so admins can import and ban in one go. The rules copy what works in the wild: numeric ids only (usernames are aliases, renaming doesn't help), no evidence, no entry (quotes carry chat and date, your own words carry the reporter), merges only add, the worst tier wins. Once a record exists, check_seller consults the list automatically: a listed account, or one sharing a payment address with a listed account, goes straight to tier D.
Checking once is not enough: market_radar is a market radar. add puts a seller (handle) or a trace (keywords / a few groups) on the watch list and takes the first snapshot; run re-checks only what is on the list (no site-wide re-crawl: tens of seconds, no rate-limit trouble) and diffs it against the last snapshot — gone, tier changed, renamed, officially flagged, new accusations, storefront or price changes, money re-routed, new sellers on a trace, convergence point moved — one line per change, pushed only when something changed. Delivery goes through RADAR_NOTIFY_CMD (a shell command that gets the text on stdin: Feishu, Slack, any notifier); with RADAR_EVERY_HOURS=24 the daemon runs it on its own once a day, timed from the last run recorded in the file so restarts don't reset it. Snapshots are dated and appended, never overwritten; history shows any watch's full timeline.
Who is the source in time: who_first takes an ad text, a storefront domain, an @handle or a wallet, searches by clues and text fragments (your groups + all public posts), groups the hits by text fingerprint (zero-width characters, interpuncts and other search-dodging tricks are stripped before comparing), and sorts each group by time: who posted it first, where and when, then which accounts followed and from which day. Forwards count by their original date and author, so the origin channel is named even when it was not searched; the opening lines alone are enough to recognise the same post. Each clue also gets its first-appearance date. The seller card gains a first_seen field — their first post in the groups or the earliest mention of them, whichever is older — so a "source" that appeared last week and a shop that has been around for two years are told apart at a glance. Limits: Telegram search is word-based and weak on long Chinese sentences, so long copy is split into short fragments; results come newest first and each term scans limit messages, and the result says when it did not reach the end.
Size up a new group first: group_profile reads its recent few hundred posts and says in one line what the group is for (marketplace / discussion / bot-flooded / one-way channel), how many members, when it started, posts per day, how much the top three posters account for, the ad share (a price, a storefront link, or sales talk plus a contact counts as an ad), how many bots post how much (official bot flag only, no guessing), which suspected same-person pairs there are (shared payment address > same storefront > same name stem > identical copy), how many accusation posts and who gets named most, plus the main storefronts, typical prices and payment addresses. The top ten posters come as a table: posts, ads among them, distinct texts, last post, storefronts, @mentions, wallets. Everything is computed from the messages themselves — no per-username lookups, no rate-limit exposure; join/leave notices and media without text are not posts. A 14k-member group profiles in 8 seconds, and the first run caught four western-named accounts posting identical copy.
Whether a quote is dear, or suspiciously cheap, needs a market to compare with: price_board reads the recent few hundred posts of the groups where the market trades, pairs each price with the product named before it (GPT Plus, Claude 20x, GPT Pro 5x, ...; price lists always read "product price", and nearest-match pairing would hand 278 to the Claude 20x that follows; a "7 days", "yearly", "seat" or "shared" between product and price makes it a separate product, so a weekly price is never judged against monthly rates), and gives per product the median, spread and a too-cheap floor (median minus three absolute deviations, clamped between 50% and 80% of the median — medians, not means: this market is long-tailed and a few absurd asks would drag a mean anywhere), the 7-day trend, the three cheapest sellers, the quotes below the floor (too good to be true, usually fakes or phishing) and the active sellers who never quote ("see the storefront", "DM me" is not missing data, it is a point against them). One seller spamming the same price list fifty times counts once, so spammers don't set the median. Once the board is saved, check_seller adds prices_vs_market to the card: each quote graded cheap / fair / dear against the market, and a quote below the floor raises a red flag and drops the seller to tier C. Five groups, 582 posts, 14 seconds; 174 GPT Plus quotes, median 99 yuan.
A scammer's core move is renaming: get exposed, drop the account, open a new one, keep selling in the same group — track by @handle and a new puppet starts with a clean record. same_person tracks what they cannot shed: reading the recent posts of a few groups, a shared payment address, the same WeChat or email, an identical full price list, or a member saying "he renamed from @a to @b" — any one of these four links two accounts; the same storefront link, identical copy, the same forward source or being named together in an exposure post are weak ties and need two; a shared name stem only tops up. Union-find turns "A with B, B with C" into one cluster; a link shared by more than eight accounts is a public platform, not a person; addresses quoted in an exposure post count against the exposed, not the victim who posted. Pass handle to see one seller's own cluster. The output is evidence, not a verdict — pairs one tie short are listed separately for a human to judge. The offline sockpuppet.py applies the same rules to scan snapshots.
The last step, "talk to people in the groups", can go to the AI too: probe_seller DMs a seller as a buyer — four default questions: price, payment, bulk price, source or reseller — or the AI writes its own, more natural set. No call blocks: start sends the first line and returns; check at any time records new replies, mines them for clues (product quotes, storefronts, payment method, wallets, "I'm a reseller / I'm the source", upstream @handles) and asks the next question; report shows the transcript and a one-line conclusion, and the seller card picks the probe up as well. Which account to use is your call — the tool does not stop you; know that a limited account can still reply to people who messaged it first, so the ban risk sits in the first message to a stranger: by default 5 new conversations a day, 10 minutes apart, one probe per person per 7 days, a typing pause before every line. All defaults, all overridable by environment variables or force=True. For safety, run a second Sherlogram with a spare account's credentials.
To share it, add report=True: the same call also writes an HTML file into your download directory — an interactive graph you can drag, zoom, filter by type, save as PNG, mask names on, and export as GEXF for Gephi, followed by the convergence points, sellers, sites and wallets tables; check_seller with report=True writes a card page with the quoted evidence. Without MCP, save the tool's JSON to a file and run python -m tg_mcp.report trace.json for the same page.
Limits: hops, sites probed, handles re-checked, wallets queried and seconds are all parameters; when a budget runs out, truncated says where it stopped. Username lookups are rate-limited by Telegram, so by default only 8 handles are re-checked, one second apart. Sites are probed by fetching the homepage only, private-network hosts are refused, page bodies are never returned. Behind a transparent proxy (fake-ip) the real IP is unknown, so "same server" cannot be judged. Site digging uses crt.sh, HackerTarget (free, 20/day) and rdap.org; sites behind Cloudflare show no same-server neighbours and registrants are usually redacted — that is the ceiling of free sources, not a missing lookup. On-chain lookups cover USDT on Tron only (where this market collects payment), through Tron's official free API: works without a key, rate-limited when busy, TRONGRID_API_KEY raises the limit; the free API gives no address labels (exchange / risk), so each result links to the explorer. Tiers are relative verifiability, not a purchase endorsement.
Related MCP server: tgx
A playbook for finding the source
trace_source automates the four steps below. To go step by step by hand (or to keep going where it lost the trail):
Scenario: you want to know where some product or service really comes from, and who the middlemen are.
Join the groups and listen —
join_chatthe relevant groups,list_messagesto read,search_globalfor keywords: who is quoting prices, which prices, which URLs.Follow the URLs upstream — take the storefront sites, look at the APIs and domains behind them, find their suppliers; collect several storefronts and the suppliers start to overlap.
Climb level by level — repeat for each supplier until you hit the source.
Cross-check back on Telegram —
get_chatto profile a person (bio, shared groups, official scam/fake flags),search_public_postsacross all public Telegram,list_messages(from_user=…)to pull one person's entire posting history in a group: real human or not, when they started, are they forwarding stale ads.
Every message carries its provenance: forwarded from where, how old the original is, whether it was edited, whether a bot posted it. Someone editing a three-month-old post to a new price and passing it off as fresh stock is obvious at a glance.
Two companion scripts make this reproducible (ask about the same seller twice, get the same verdict):
market_watch.py— re-check a list of sellers: still around, still active, old posts still up; scan negative-sentiment corpora; diff against the previous snapshot. Comparing across time is the whole point, so every output is dated and never overwritten.sockpuppet.py— offline sockpuppet clustering: which accounts are the same person.
Quick start
git clone https://github.com/jackchen175x/sherlogram && cd sherlogram
uv sync
cp .env.example .env # fill TELEGRAM_API_ID / TELEGRAM_API_HASH from my.telegram.org/apps
uv run python relogin.py # log in with the code sent to your phone; the session string is written to .envConnect to Claude Code (pick one):
# Option 1: one process per window (simple, but several windows at once will kick each other out — see below)
claude mcp add -s user telegram -- uv --directory /path/to/sherlogram run python main.py ~/Downloads
# Option 2: one shared daemon for the whole machine, every window connects by URL (recommended)
uv run python main.py --http ~/Downloads ~/Desktop &
claude mcp add --transport http -s user telegram http://127.0.0.1:8799/mcpThe directories at the end of the command are the only places file tools may read from or write to; omit them and those tools are disabled (see "Safety").
Tools (49)
One tool per kind of thing, with an action parameter choosing what to do — so the tool list is a third the size of the original 98-tool version with nothing missing.
Area | Tools |
Investigation |
|
Me |
|
Chats, channels, people |
|
Messages |
|
Search |
|
Contacts |
|
Folders |
|
One session string, one process
If the same session string is used by two processes at once (two windows, Claude plus another tool, two machines), Telegram revokes it: everything disconnects and you have to log in again with a phone code. So:
Run one daemon (
--http) and point every window at the URL. While the daemon is running, startingmain.pyin stdio mode refuses to start.macOS launch-at-login example:
examples/launchd.plist; the process exits on its own above 2 GB RSS (TG_MCP_MEMORY_LIMIT_MB) and launchd restarts it.Another machine or another tool that needs Telegram: register another account and get its own session string.
After a revocation you'll see
AuthKeyDuplicated: runuv run python relogin.py(the old string is backed up to.env.bak).
Safety
Sending files, downloading and changing photos may only touch the directories given at startup; with none given those tools are disabled.
..and shell wildcards in paths are rejected; voice notes must be .ogg/.opus, stickers .webp, photos image types, each with a size cap. In stdio mode the client's MCP Roots take precedence.The daemon binds
127.0.0.1only, accepts only localHostheaders and no webOrigin, so a web page cannot reach it through your browser (DNS rebinding).Errors are raised, not returned as strings, so the MCP layer sets
isError— otherwise an AI running a batch investigation would read "connection lost" as "this seller has no negative history".
Troubleshooting
Cannot connect: check
mcp_errors.log(JSON, warnings and above);LOG_LEVEL=INFOfor moreRate limited (FloodWait): wait the number of seconds shown; numeric IDs trigger fewer limits than @usernames (username resolution hits the server every time)
Slow start: the first run pulls all dialogs to warm the cache, 10–30 s; past
TG_MCP_STARTUP_TIMEOUT(default 45 s) it exits rather than hold the sessionTests:
TG_MCP_LOG=/dev/null uv run pytest -q
License
Apache-2.0. Forked from chigwell/telegram-mcp.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Source-linked crypto research tools, market observations and user-owned agent tasks.
Your personal Telegram account for AI: read, search and sum up chats. QR login, no API key.
Token rug-risk scans, Know Your Agent wallet checks and deployer reputation for AI agents.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to scoped, permissioned access to Telegram chats with per-chat read/write levels and human approval for sending messages.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate a Telegram account through the same commands as the terminal client: messaging, chat management, voice transcription, calls, stickers, and privacy settings.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and act on Telegram conversations, groups, channels, files, and links, with semantic search, AI-powered knowledge extraction, human-in-the-loop approvals, and PostgreSQL/pgvector persistence.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to work with Telegram through explicitly selected user accounts and bots, supporting search, reading, sending, and message management with consent-based access.50 PyPI1Apache 2.0