telegram-keyword-search
This server lets you search public Telegram channels for keywords — either for free in channels you name, or via a paid hosted search that also discovers the channels for you.
search_telegram_channels(free, no API key or Telegram account): searches up to 10 public channels you specify for a keyword, returning post link, date, views and text; keeps only exact-phrase/#hashtag matches unlessinclude_allis set; up to 20 newest results per channel.start_keyword_search(paid, needsAPIFY_TOKEN): starts a hosted search that finds channels talking about each keyword (via Googlesite:t.me), with options for match mode, date range, only-new-posts, channel/post limits and a USD spending cap; returns arun_idimmediately.get_keyword_results(free): polls a started search byrun_id(waiting up to 45s) and returns the matching posts once finished, or a still-running message to retry.Typical use: ask about a known channel's posts on a topic, or discover and monitor channels mentioning a keyword over a date range.
Provides tools for searching public Telegram channels by keyword without an account, returning matching posts with links, dates, views, and text; also supports hosted searches that discover relevant channels, filter by date, and return only new posts.
Telegram Keyword Search (Python) - search public channels without logging in
A small Python script that searches public Telegram channels for a keyword and returns only the posts that really contain it. No Telegram account, no phone number, no API key, no dependencies beyond the standard library.
For each channel you name, it runs Telegram's own in-channel search and gives you the post link, date, views and full text, marked as an exact-phrase or #hashtag match. Export JSON or CSV.
python telegram_keyword.py "end-to-end encryption" durov telegramAlso works as an MCP server for Claude, Cursor and other AI clients: a free search_telegram_channels tool, plus a hosted search that also finds the channels for you. See Use it as an MCP server.
Can you search Telegram without an account?
Telegram's official API needs a Telegram account (phone number) and an api_id. But every public channel with the web preview turned on has a page anyone can open, https://t.me/s/<channel>, and that page has a search box. This script calls the same URL your browser does:
GET https://t.me/s/<channel>?q=<keyword>and reads the posts from the HTML. telegram_keyword.py is about 250 lines and you can read all of it in a few minutes.
Related MCP server: Reddit MCP Server
Quick start
Requires Python 3.8+. Nothing to install for the script (the MCP server needs pip install -r requirements.txt).
git clone https://github.com/datalumehq/telegram-keyword-search.git
cd telegram-keyword-search
python telegram_keyword.py privacy durovOr download telegram_keyword.py on its own and run it.
Options
Option | What it does | Example |
| Word or phrase to find (required) |
|
| Public channels: username, |
|
| Keep every post Telegram's search returns, not only exact matches |
|
| Write CSV instead of printing JSON |
|
The script prints one status line per channel to stderr, e.g. durov: ok, Telegram returned 20, kept 19. notFound means there is no public channel with that name, or its web preview is turned off.
Output
Real output from 20 November 2026 (privacy in durov; Telegram returned 20 posts, 19 contained the word; text shortened here):
[
{
"keyword": "privacy",
"matchType": "phrase",
"channel": "durov",
"postId": 520,
"postUrl": "https://t.me/durov/520",
"date": "2026-05-23T13:26:07+00:00",
"views": 11700000,
"text": "🎭 WhatsApp encryption is a giant fraud. ..."
}
]Posts are newest first. matchType is phrase (the keyword as written, case-insensitive, whole words), hashtag (#EndToEndEncryption for "end to end encryption") or telegram (only with --all: returned by Telegram's search without an exact match).
Why check the phrase again?
Telegram's channel search matches words, not phrases: search for bitcoin ETF and you also get posts that mention "bitcoin" in one sentence and "ETF" in another. In a test on 15 November 2026 (three keywords, 19 channels), 211 of 470 search results did not contain the exact phrase. This script keeps only the posts that do, unless you pass --all.
One trap if you write your own: on search pages Telegram wraps every matched word in <mark>, so end-to-end arrives as <mark>end</mark>-<mark>to</mark>-<mark>end</mark>. Joining the text with a separator (BeautifulSoup's get_text(" ")) breaks the phrase; this script joins text nodes as they are.
What this script does not do
You have to know the channels. Telegram has no public search across all channels, so the hard part of keyword monitoring is finding which channels talk about a keyword in the first place, then searching each of them deeper than one page and only returning what is new since last time.
That part (channel discovery, page-by-page search, date filters, only new posts, retries) is what the hosted version below does. This script stays small on purpose.
Limits of this script
One search page per channel: Telegram returns up to 20 results, newest first. Older matches are not fetched.
Up to 10 channels per run, one request per channel with a 1-second pause.
Only public channels with the web preview (
t.me/s/...) turned on. Private channels, groups and comments are not available.A channel that does not exist still answers HTTP 200, so the script detects it from the page content (no channel info, no posts) and reports
notFound.The page layout is Telegram's and can change without notice. If the script breaks, please open an issue.
Hosted version: finds the channels for you
If you don't know which channels to search, need more than 20 results per channel, or want a feed of new mentions, the same approach is available as a maintained Apify Actor: Telegram Keyword Search Scraper - Mention Alerts, No Login.
It adds:
Finds channels for each keyword with Google (
site:t.me); when Google finds only a few, it also searches the channels that matching posts were forwarded from or link toSearches inside every channel page by page, so it finds recent posts Google hasn't indexed
Match modes: exact phrase or #hashtag, all words, or everything Telegram returns
Date range (
7 days,2026-11-01), only new posts since the last run for scheduled mention alertsReactions, media, forwards, links and channel info per post
Pay per matching post; non-matching posts and unreadable channels are not charged (price on the Actor page)
From Python (pip install apify-client, see run_apify_actor.py):
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("datalume/telegram-keyword-search-scraper").call(run_input={
"keywords": ["Hyperliquid"],
"discoverChannels": True,
"maxChannelsPerKeyword": 10,
"dateFrom": "7 days",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item["date"], item["channel"], item["views"], item["matchedText"])The same features are available to AI agents through the MCP server below (start_keyword_search).
Use it as an MCP server
mcp_server.py exposes three tools to any MCP client (Claude Desktop, Claude Code, Cursor, VS Code). Requires Python 3.10+.
Tool | Cost | What it returns |
| Free, no API key | Exact-phrase matches for a keyword in channels you name: post link, date, views, text. Up to 20 newest search results per channel, 10 channels |
| Paid per matching post through your Apify account (price on the Actor page) | Starts a search that also finds the channels for each keyword and returns a |
| Free (reads the results of a search you started) | The matching posts once the search has finished. While it is still running it says so and the client calls it again |
Why two steps: a hosted search takes from a few seconds to over two minutes (2 min 15 s for 3 keywords and 19 channels in our 15 November 2026 test), and some MCP clients stop waiting for a single tool call before that. Starting the search and fetching the results separately keeps every call short.
Install:
git clone https://github.com/datalumehq/telegram-keyword-search.git
cd telegram-keyword-search
pip install -r requirements.txtClaude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and most other clients use the same block. Use the full path to mcp_server.py:
{
"mcpServers": {
"telegram-keyword-search": {
"command": "python",
"args": ["/path/to/telegram-keyword-search/mcp_server.py"],
"env": { "APIFY_TOKEN": "<optional, only for start_keyword_search and get_keyword_results>" }
}
}
}Claude Code:
claude mcp add telegram-keyword-search -- python /path/to/telegram-keyword-search/mcp_server.pyThen ask in plain language, for example:
"Did @durov post anything about privacy recently? Give me the links" (free)
"Find Telegram channels talking about Hyperliquid in the last 7 days and show the most viewed posts" (uses
start_keyword_search)
Without APIFY_TOKEN the free tool works and the other two return a message explaining how to add a token. Get a token at console.apify.com/settings/integrations.
Prefer not to run anything locally? Apify's hosted MCP endpoint serves the same Actor: https://mcp.apify.com?tools=datalume/telegram-keyword-search-scraper (sign in with Apify on first use).
FAQ
Do I need a Telegram account or API key? No. The script reads the public web preview pages that anyone can open without logging in.
Can it search all of Telegram? No tool without an account can. This script searches the channels you give it; the hosted version first finds channels that talk about your keyword.
Is it allowed? The pages are public and served to anyone without logging in. This script reads them the way a browser does, one request per channel with a pause. Use it responsibly and check the terms that apply to you.
Why do I get fewer posts than I expected?
Only the first search page (up to 20 results) per channel is read, and posts without the exact phrase are dropped. Try --all to see what Telegram returned.
Does it work for private channels or groups? No. Only public channels with the web preview turned on.
More
Tutorial: How to Search Telegram for a Keyword Without Logging In (and Why Google Misses Most Posts)
Every post from specific channels: Telegram Channel Scraper
Other scrapers by datalume: apify.com/datalume
License
MIT. Built with AI assistance; numbers come from real runs on the dates shown.
Not affiliated with, endorsed by or sponsored by Telegram or Google. "Telegram" is a trademark of Telegram FZ-LLC. This project only reads publicly available channel posts.
Available Tools
3 toolsget_keyword_resultsA
Get the posts found by a search started with start_keyword_search. Step 2 of 2. Reading results is free; it never starts a new search.
Waits up to wait_secs for the search to finish. Returns {"finished", "status", "posts",
"message"}. If "finished" is false the search is still running and "posts" is empty:
call get_keyword_results again with the same run_id (do not start a new search).
Args:
run_id: the run_id returned by start_keyword_search.
wait_secs: how long to wait for the search to finish, 0-45 seconds.
Inputs: run_id (required), wait_secs.
search_telegram_channelsA
Search public Telegram channels that you name for a keyword. Free, no API key, no Telegram account.
Uses Telegram's own in-channel search on the public web preview (t.me/s/<channel>) and
keeps only posts that contain the keyword as written or as a #hashtag. Returns at most
the 20 newest search results per channel, up to 10 channels. It does NOT find channels
for you; use start_keyword_search when you don't know which channels talk about the keyword,
or need more posts, dates or only new posts.
Args:
keyword: word or phrase, e.g. "end-to-end encryption" or "Solana".
channels: public channel usernames or links, e.g. ["durov", "@telegram", "t.me/s/cointelegraph"].
include_all: keep every post Telegram's search returns, not only exact matches.
Returns {"posts": [...], "channels": [{"channel", "status", "returned", "kept"}]}.
status "notFound" means no public channel with that name or its web preview is off.
Inputs: keyword (required), channels (required), include_all.
start_keyword_searchA
Start a Telegram keyword search that also FINDS the channels talking about each keyword, and return a run_id immediately. Step 1 of 2: then call get_keyword_results(run_id) to get the posts.
Starts the hosted Apify Actor "datalume/telegram-keyword-search-scraper" with your own
Apify account. Requires the APIFY_TOKEN environment variable. It is PAID: per matching
post plus a small fee per keyword when channels are found (current price:
https://apify.com/datalume/telegram-keyword-search-scraper ); non-matching posts and
unreadable channels are not charged. Starting a search spends money even if the results
are never fetched, so start one only when the user wants the posts. The run stops at
max_posts_per_keyword and at max_total_charge_usd. A run takes from a few seconds to
about two minutes (15 Nov 2026: 3 keywords, 259 posts from 19 channels in 2 min 15 s).
Args:
keywords: words or phrases, e.g. ["Hyperliquid"]. Each keyword is searched separately.
channels: optional channels that are always searched, e.g. ["durov"].
discover_channels: find channels for each keyword with Google (site:t.me). Set false to search only `channels`.
max_channels_per_keyword: found channels searched per keyword, 1-50.
match_mode: "phrase" (exact phrase or #hashtag), "allWords" or "telegram" (everything Telegram returns).
max_posts_per_keyword: stop a keyword after this many matching posts. Keep small to control cost.
date_from: only posts since a date ("2026-11-01") or a period ("7 days", "24 hours"). Empty = any date.
only_new_posts: return only posts published since the previous run of the same keyword in each channel.
max_total_charge_usd: hard spending cap for this search, in USD.
Inputs: keywords (required), channels, date_from, match_mode, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The two search tools overlap in domain (both search Telegram by keyword), but the descriptions clearly separate the free named-channel search from the paid channel-discovering search. get_keyword_results is clearly a retrieval step and cannot be confused with either search tool.
All three tools use snake_case with a verb-first pattern: search_telegram_channels, start_keyword_search, get_keyword_results. The start/get pair also signals a coherent two-step workflow.
Three tools are well-scoped for a narrow keyword-search server: a direct search, an asynchronous discovery search, and a results fetcher. The async split is justified by the long-running paid operation.
The surface covers both the free direct-search workflow and the paid discovery-then-retrieval lifecycle. Minor gaps exist around run management (e.g., cancel or list runs) and channel inspection, but core keyword-search tasks are covered.
Maintenance
Related MCP Connectors
Telegram for AI agents, no login: keyword search, channel posts, comments, username lookup.
Search public Telegram posts by keyword, mention or ticker, with date and views filters.
Search 1.7M+ Telegram channels, 250k+ chats, 228k+ bots, and what chats ask for. No key, no install.
Search millions of Telegram channels: metrics, growth, ads, posts and row-priced exports.
Related MCP Servers
AlicenseAqualityBmaintenanceUse 3,000+ pre-built cloud tools from Apify, known as Actors, to extract data from websites, e-commerce, social media, search engines, maps, and more1344,412 npm17,150MIT- AlicenseBqualityDmaintenanceEnables AI agents to search Reddit for posts, comments, and users or monitor for high-intent leads and brand mentions. It functions by delegating scraping tasks to high-performance Apify cloud actors.261 npm7MIT
- AlicenseAqualityBmaintenanceEnables searching and retrieving public-sector opportunity data — US federal contract opportunities, grants, and awards, UK and EU tenders, and city council agendas and votes — with official source links on every record. Runs as a hosted remote MCP server via Apify's gateway, so clients can query these feeds and pull run results through natural language.61MIT
- AlicenseAqualityBmaintenanceEnables querying public Bluesky posts by keyword, account, or post address through Apify, with options for replies, reposts, date and language filters, and exact engagement counts.1114 npmMIT