reach-mcp

A controllable multi-source search MCP server for AI agents. Search Reddit, X, YouTube, Hacker News, GitHub, arXiv, Polymarket, 微博, 知乎, 豆瓣, 头条, 雪球, V2EX, B站, 小宇宙 and more -- you pick the sources, the window, and whether to synthesize. 33 sources across Chinese & English platforms, with adjustable time window, source/category scoping, trending hot lists (微博/知乎/头条热搜...), and optional LLM synthesis.

---

Why

last30days (mvanhorn/last30days-skill) wraps the search in a fixed pipeline: the agent passes a query and gets back a finished brief. It can't choose which sources to hit, can't widen or narrow the time window (hardcoded to 30 days), can't see the raw scored rows, and can't reuse them. Every call re-searches everything.

reach-mcp keeps the same core machinery -- parallel multi-source fetch, engagement-based scoring, cross-source dedup/clustering, an optional LLM-synthesized cited brief -- and exposes it as a plain MCP server whose knobs the agent controls per call:

• 🔌 Pick your sources. sources=["reddit","arxiv","xueqiu"] or omit for all configured ones.
• 📅 Pick your window. days=7 for this week, days=180 for the half-year -- no longer fixed at 30.
• 🪓 Decide what matters. synthesize=false returns raw scored rows for the agent to reason over itself; synthesize=true (default) also runs an LLM rerank + brief. max_chars_per_item sets each row's text-snippet length (default 500) -- raise it for fuller CN posts, lower it to save tokens.
• 🌐 Chinese & English sources in one call -- 微博, 知乎, 豆瓣, 头条, 雪球, V2EX, B站, 小宇宙, 小红书 alongside Reddit, X, YouTube, HN, GitHub, arXiv and the rest.
• 🛡️ Polite by default -- per-host pacing, honors Retry-After, bounded timeouts. Never hammers a site.

Sources (33)

| Tier | Source | Backend | Credential | |------|------|------|------| | Free core | reddit | RSS + scrape | none | | | hackernews | Algolia API | none | | | bluesky | AT Protocol (public) | BSKY_HANDLE/BSKY_APP_PASSWORD (optional) | | | github | GitHub API | GITHUB_BASE_URL (proxy w/ token pool) or GH_TOKEN (both optional) | | | arxiv | arXiv API | none | | | techmeme | scrape | none | | | polymarket | public API | none | | | stocktwits | public API | none | | | web | Searxng + Brave (optional) | SEARXNG_URL; BRAVE_API_KEY optional ($5/mo) | | | dripstack | DripStack API (free, keyless) | none | | | stackoverflow | Stack Exchange official API (keyless, Q&A corpus) | none | | | lobsters | Lobste.rs JSON feeds (keyless; search = feed filter) | none | | | rss | feedparser | RSS_FEEDS (comma-separated feed URLs) | | Video | youtube | yt-dlp metadata; captions via fetch_content | YTDLP_PROXY (optional) | | Chinese | xueqiu | API (login cookie) | XUEQIU_COOKIE | | | v2ex | API | none | | | bilibili | bili-cli (preferred) / public API fallback | none (install bili for stability) | | | xiaoyuzhou | public API | XIAOYUZHOU_ACCESS_TOKEN (login); WHISPER_BASE_URL (for fetch_content transcription) | | | xiaohongshu | xiaohongshu-mcp companion | XHS_MCP_URL | | | weibo | mobile API (m.weibo.cn) + auto visitor cookies | none | | | zhihu | search via ZHIHU_COOKIE; hot-list via mobile API | ZHIHU_COOKIE (optional — unlocks real search) | | | douban | mobile rexxar API (movies/TV/books/music + ratings) | none | | | toutiao | hot-board JSON API + search SSR scrape | none | | | linuxdo | playwright + login cookie (Cloudflare-gated Discourse) | LINUXDO_COOKIE (login) + playwright/chromium | | Login-gated (off by default) | x | cookies | AUTH_TOKEN/CT0 | | | truthsocial | Mastodon API | TRUTHSOCIAL_TOKEN | | | linkedin | Apify (public posts) + Searxng fallback + ScrapeCreators (optional) | APIFY_API_TOKEN ($5/mo); SEARXNG_URL for fallback; SCRAPECREATORS_API_KEY optional | | | tiktok | playwright in-page fetch (free, optional) / Apify / OpenCLI / ScrapeCreators | none (with playwright+chromium installed); else APIFY_API_TOKEN ($5/mo); SCRAPECREATORS_API_KEY; or opencli on PATH | | | instagram | Apify / OpenCLI / ScrapeCreators | APIFY_API_TOKEN ($5/mo); SCRAPECREATORS_API_KEY; or opencli on PATH | | | pinterest | Apify / OpenCLI / ScrapeCreators | APIFY_API_TOKEN ($5/mo); SCRAPECREATORS_API_KEY; or opencli on PATH | | | threads | playwright SSR scrape (free, optional) / Apify | none (with playwright+chromium installed); else APIFY_API_TOKEN ($5/mo) | | Binary (optional) | digg | digg-pp-cli | none (needs the CLI on PATH) | | Apify | quora | Apify quora-search-scraper | APIFY_API_TOKEN ($5/mo recurring) |

💰 Apify gives $5 free credits EVERY MONTH (recurring, not one-time) on the Free plan -- enough for hundreds of search runs. Set APIFY_API_TOKEN to enable quora + boost tiktok/threads/instagram/pinterest/linkedin. tiktok and threads have FREE playwright backends (in-page fetch / SSR scrape) that need no credential at all when playwright+chromium is installed.

⚠️ ScrapeCreators is 100 credits one-time, not free recurring. It's now the lowest-priority fallback for tiktok/instagram/pinterest -- prefer Apify (monthly free) or OpenCLI (desktop, free). LinkedIn uses Apify for public posts (same APIFY_API_TOKEN, no LinkedIn login).

Query syntax by source

Each source has its own search-query rules. Multi-word/long queries may return fewer results on some backends — the agent should tune the query per source.

| Source | Query syntax | Notes | |--------|-------------|-------| | bluesky | Lucene: space=AND, "quoted phrase", from:handle, lang:code, #tag, (a OR b), -term | Phrase/boolean recommended | | stocktwits | ticker/crypto only (AAPL, $BTC, BTC) | Non-financial topics return []; resolved via symbol search | | x | Literal keyword AND — all words must appear | Long/multi-word queries may return few results | | techmeme | Phrase, wildcard, AND/OR/NOT, sourcename:X | Supports quoted phrases | | reddit | Space-separated words | Multiple feeds searched | | digg | Phrase match | CLI-based | | arxiv | arXiv syntax: all:, ti:, au:, quoted, boolean | Official Atom API | | web | Space-separated (Searxng/Brave) | Free-text | | rss | Substring match on title/summary | Filter over configured feeds | | v2ex | Keyword search via sov2ex ES index | Topics + replies | | youtube | yt-dlp search query | Free-text | | xiaoyuzhou | Podcast keyword search | Requires login token |

General guidance: prefer short, specific keywords (2-4 words). Very long queries or phrases that only a specific site would phrase identically will often return [] — the backend isn't broken, the query is too specific.

MCP tools

search -- the primary tool

Description:

Search up to 33 social & web sources in parallel, score by engagement, optionally synthesize a cited brief. YOU control scope.

Best scoping: category -- social: x, reddit, instagram, threads, tiktok, xiaohongshu, bilibili, youtube, pinterest, bluesky, linkedin, web, weibo, zhihu, douban, toutiao; it: github, hackernews, v2ex, rss, arxiv, dripstack, stackoverflow, lobsters; tech: arxiv, techmeme, digg, dripstack, hackernews; polec (politics & economics): truthsocial, xueqiu, stocktwits, polymarket; podcast: xiaoyuzhou; web: web (general web search — also part of social). Categories overlap (e.g. arxiv is both it and tech) -- multiple categories union. sources picks individual names; both together = union; both omitted = all available sources EXCEPT podcast (xiaoyuzhou is opt-in: episode transcription is slow, request it explicitly when you need podcasts). Search returns metadata + a snippet per item -- xiaoyuzhou/youtube/bilibili are NOT transcribed/captioned here. With synthesize=true the top rich-media items are auto-backfilled with full content before the brief; with synthesize=false call fetch_content on any item you want in full. max_chars_per_item caps snippet length (raise for fuller CN posts, lower to save tokens).

Returns {brief, items, sources_used, source_summary, available_sources}. Each item: {source, title, url, author, date, score, engagement, text}. source_summary is one compact line per outcome -- 'x:3; reddit:5 | EMPTY: rss, v2ex | QUOTA: tiktok(monthly limit) | ERRORS: digg(429) | NOTICE: zhihu(ZHIHU_COOKIE search failed — showing 热榜 instead; refresh the cookie)'; 'gated_off' means its credential env isn't set; NOTICE marks a degraded-but-working source (stale cookie fell back to a limited path) — usable data, but surface the caveat. Match query language to platform -- Chinese keywords work best for the CN sources. WeChat 公众号 queries on web auto-scope to mp.weixin.qq.com. Call list_sources if unsure what's configured.

list_sources

Inventory of all registered sources. Call before search when unsure what's active. Returns [{name, description, needs_auth, available, required_env, default_days, default_limit}]: available=false = gated (credential in required_env not set). No arguments.

synthesize

LLM-synthesize a cited brief from items returned by a prior search(synthesize=false), WITHOUT re-searching. Args: query (the original), items (the prior items list). Returns {brief}.

fetch_content

Fetch the full content of ONE item found via search. Two-stage retrieval: search returns metadata + a snippet for every source; call this when an item is worth reading/hearing in full. Rich-media sources have dedicated backends -- xiaoyuzhou (pass the item's audio_url → Whisper transcript), youtube (watch URL or video id → captions), bilibili (video URL → CC subtitles if any); every other source falls back to Jina Reader on the item's url. Args: source, id_or_url. Returns {source, url, content, ok}.

read_url

Fetch any URL as clean markdown via Jina Reader. Use for the full text of a page found via search -- a thread, article, or repo -- when the item's text snippet isn't enough. Returns {url, content, ok}; content is '' on failure. Keyless.

For agents -- quick usage guide

1. list_sources()                         # see what's configured; pick targets
2. search("Peter Steinberger",
          sources=["reddit","x","github","youtube"],
          days=14, synthesize=false)      # get raw scored rows, reason yourself
   -- or --
   search("OpenAI vs Anthropic",
          category=["tech","it"],
          days=30, synthesize=true)          # scope by topic group
   -- or --
   search("OpenAI vs Anthropic",
          days=30, synthesize=true)          # one call → cited brief + rows
   -- or --
   search("", trending=true,
          sources=["weibo"])              # hot lists, not keyword search
3. (optional) synthesize(query, items)     # re-brief the rows you already have

• Default (sources=None, category=None, synthesize=true): searches every configured source EXCEPT podcast (opt-in), auto-backfills full content for the top rich-media items, and returns a cited brief + all rows. Simplest.
• By type (category=["tech"]): one keyword scopes to a topic group (social / it / tech / polec / podcast / web) -- the easiest way to match the sources to the kind of query. Categories overlap; several union together.
• Targeted (sources=[...]): only hit what you need -- faster,