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. Built to replace the closed last30days server with an open, agent-driven one.

Why

last30days is a black box: 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 everything good about last30days — parallel multi-source fetch, engagement-based scoring, cross-source dedup/clustering, an optional LLM-synthesized cited brief — and hands the steering wheel to the agent:

• 🔌 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.

• 🇨🇳 Chinese sources last30days lacks — 雪球, V2EX, B站, 小宇宙 — alongside nearly every source last30days ships.

• 🛡️ Polite by default — per-host pacing, honors Retry-After, bounded timeouts. Never hammers a site.

Related MCP server: MetaSearchMCP

Sources (23)

Login-gated sources are off by default and light up the moment you set their (free) credentials — an account you already have, no payment. Only perplexity from last30days was dropped (no recurring free quota).

MCP tools

The description text below is exactly what the agent sees — copy these verbatim into src/reach_mcp/tools.py.

search — the primary tool

Description:

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

Sources (pass any subset as sources; omit/None = all currently-configured): free — reddit, hackernews, bluesky, github, arxiv, techmeme, polymarket, stocktwits, web; video — youtube; chinese — xueqiu, v2ex, bilibili, xiaoyuzhou; login-gated (off until creds set) — x, truthsocial, tiktok, instagram, linkedin, xiaohongshu, threads, pinterest; binary — digg.

Args: query (str, the topic/person/ticker); sources (list[str] | None, None=all available); days (int, recency window, default 30); max_per_source (int, row cap per source, default 20); synthesize (bool, default true = also LLM-rerank + write brief).

Returns: {brief: str|null, items: [Item], sources_used: [SourceReport], available_sources: [str]}. Each Item: {source, title, url, author, date, score, engagement, text}. A SourceReport tells you per-source ok/gated_off/errored so a thin result is diagnosable. Call list_sources first if unsure what's configured.

Signature:

search(query: str, sources: list[str] | None = None, days: int = 30,
       max_per_source: int = 20, synthesize: bool = True) -> dict

list_sources

List all registered sources with availability status, required credentials, and defaults. Call this FIRST to see which sources are active (credentials set) vs gated (off-by-default) before deciding sources. Returns [{name, description, needs_auth, available, required_env, default_days, default_limit}]. No arguments.

synthesize

Re-synthesize a cited brief from already-fetched items WITHOUT re-searching. Pass the original query and the items list from a prior search(synthesize=false). Returns {brief}. Use to re-brief cheaply with different emphasis. No source calls are made.

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",
          days=30, synthesize=true)        # one call → cited brief + rows
3. (optional) synthesize(query, items)     # re-brief the rows you already have

• Default (sources=None, synthesize=true): searches every configured source and returns a brief + all rows. Simplest.

• Targeted (sources=[...]): only hit what you need — faster, cheaper, less noise.

• Raw (synthesize=false): you read the rows and draw conclusions; re-brief later with synthesize.

• A gated source you name returns gated_off in sources_used — set its credential env and retry, or drop it.

• One broken source never breaks a search; check sources_used for what failed.

Install

Option A — uvx in your MCP host (recommended for OpenWebUI / mcpo)

// mcpo config.json
"reach": {
  "command": "uvx",
  "args": ["reach-mcp", "--transport", "stdio"]
}

Or streamable-HTTP: uvx reach-mcp --transport http --host 0.0.0.0 --port 8765.

Option B — Docker

docker pull ghcr.io/xyonium/reach-mcp:latest
docker run -p 8765:8765 --env-file .env ghcr.io/xyonium/reach-mcp:latest

# docker-compose.yml
services:
  reach-mcp:
    image: ghcr.io/xyonium/reach-mcp:latest
    ports: ["8765:8765"]
    environment:
      REACH_MCP_ALLOWED_HOSTS: "reach-mcp:8765,localhost:8765"
      # …credentials below…
    restart: unless-stopped

OpenWebUI connects to http://reach-mcp:8765/mcp (native MCP, streamable-HTTP).

Configuration

All config is environment variables (a Settings dataclass). Everything is optional — the server degrades to free-source-only mode if you set nothing.

For digg: install digg-pp-cli on PATH (see last30days' build steps) — reach-mcp detects it and enables the source automatically; without it, digg stays gated.

License

MIT © xyonium