social-search-mcp
Provides tools for searching Reddit and reading full comment trees, with features like cross-subreddit deduplication, engagement-based re-ranking, and configurable search modes (discussion, fresh, evergreen), returning raw structured data via a self-hosted Redlib instance.
Social Search
Personal Codex plugin for Reddit and X search and post retrieval. It packages a short Skill and four MCP tools around one tested provider implementation. The CLI and legacy HTTP adapters reuse that implementation.
Installed Architecture
Codex plugin -> existing SSH connection -> VPS stdio MCP
|- Reddit -> loopback Redlib -> Reddit
`- X -> TwitterAPI.io
Existing n8n -> Docker bridge -> legacy HTTP adapters -> same providers
Browser -> Cloudflare -> nginx -> Redlib (static/media cache; dynamic no-store)Current repair and rollback evidence: 2026-09-07 verification.
The MCP transport has no public listening port. Configure scripts/connect-vps
with SOCIAL_SEARCH_VPS_HOST, SOCIAL_SEARCH_VPS_PORT, SOCIAL_SEARCH_VPS_KEY,
and (when needed) SOCIAL_SEARCH_VPS_USER; no host address, key or credential is
included in this repository. X credentials are read inside the VPS process from
the protected runtime configuration.
Related MCP server: hidrix-tools
Tools
Tool | Behavior |
| Native ordering, canonical source URLs, bounded session pagination |
| Original post and comments, parent IDs, hard count/depth limits, coverage |
| One complete provider page, original order, IDs and next cursor |
| Read requested IDs and available quote/reply context; report missing IDs |
Errors remain errors, including authentication, quota, rate limits and malformed upstream pages. Results retain source links and distinguish returned content from loaded or source-reported totals. Comment permalink pages disclose unknown parents.
Reddit search cursors expire after 15 minutes and belong to one server process. A new Codex task or restarted MCP server requires a new search. Separate CLI invocations cannot continue those in-memory cursors. X calls use an existing paid third-party account and are not automatically retried. A page is usually 20 posts; requesting fewer locally does not reduce the upstream page charge.
Development
Node.js 22 or newer is required for the provider package on the VPS. The installed
local bridge requires only SSH. Dependencies are pinned in package-lock.json.
npm ci --ignore-scripts
npm test
node src/cli.mjs doctor
node scripts/verify-live.mjs ./scripts/connect-vpsThe final command performs live Reddit requests and a small paid X search/read.
Use it deliberately, not as a periodic free health probe. The ordinary X health
endpoint checks configuration only and explicitly says upstream_verified:false.
Compatibility and Caching
Existing Reddit GET /api/search, GET /api/post, and X POST /api/search routes
remain available on loopback and Docker bridge addresses. Legacy Reddit modes are
accepted as labels, with native ordering; old popularity filters are removed.
The legacy X limit is an explicitly reported preview and may omit rows from the
provider page. Use MCP for full-page pagination.
All /api/ responses bypass nginx cache and declare private, no-store for CDN
caches. Normal Redlib webpage and media caching remains enabled. MCP reads Redlib
on loopback directly, bypassing both nginx and Cloudflare page caches.
See deployment verification for observed results, current release locations, rollback steps, and remaining boundaries.
Provenance
The archived reference repository was reviewed at commit
3e9dea1951ce359f9232378efb6edb81126d1526; its source remains untouched. The new
package lives separately. Real HTML fixtures were captured from the existing
Redlib deployment. The comment-template fixture comes from Redlib commit
a4d36e954cf1bd64f209cd8868c5a29edc81b374. Upstream fixtures retain their respective
project provenance. This package is private and no publication license is granted.
Available Tools
4 toolsreddit_postARead-onlyIdempotent
Read a Reddit post and loaded comments with original links, parent IDs and explicit coverage. The count is a hard budget; results are not a complete or unbiased survey. Follow next_links for more threads.
Inputs: url (required), sort, maxDepth, maxComments.
reddit_searchARead-onlyIdempotent
Search Reddit with original ordering and canonical links. Cursor is valid only within this server session for 15 minutes; keep query and filters unchanged when paging.
Inputs: query (required), sub, sort, time, +2 more.
x_postARead-onlyIdempotent
Read X posts by numeric ID through TwitterAPI.io, including available quotes and reply references. Reports missing IDs; does not fetch a full reply thread. Billed per returned post.
Inputs: ids (required), detail.
x_searchARead-onlyIdempotent
Search X through TwitterAPI.io. Returns one whole upstream page (normally up to 20 posts), preserving Latest or Top order and reply/quote context. Billed per returned post. Pass next_cursor to page; no automatic retries or popularity filters.
Inputs: query (required), sort, cursor, detail.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool pairs a platform with a clear action (search vs. reading a specific post), so boundaries are largely distinct. The verb 'post' is mildly ambiguous since it means 'read a post object' rather than 'publish', but descriptions resolve this.
All four tools follow a strict platform_action pattern (reddit_search/reddit_post, x_search/x_post) with consistent snake_case and parallel verb usage across both platforms.
Four tools is well-scoped: a symmetric 2x2 grid of two platforms times two operations (search and read). Every tool earns its place with no redundancy.
Search-plus-read coverage exists for both Reddit and X, including comment/quote context and pagination. Gaps remain for user/timeline lookups and full reply threads (x_post explicitly does not fetch them), but core workflows are workable via next_links/cursors.
Maintenance
Related MCP Connectors
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned. Separately, TwitterAPI.io also offers x402 pay-per-call HTTP endpoints (tweet search, user info, a user's latest tweets) paid in USDC on Base or Solana with no account or API key; see https://docs.twitterapi.io/x402-pay-per-call. The MCP server itself uses an API key or sign-in.
Reddit & X data for AI agents over MCP. Semantic search, hosted, no Reddit API.
Hosted MCP with 91 agent tools: X, domains, SEO, Maps, Trends, Search, YouTube, TikTok, and more.
Live X/Twitter and Reddit research. 10 read-only MCP tools, Google/GitHub sign-in. Free tier.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for Twitter/X enabling AI agents to search, post, reply, and engage with tweets.147 npm2MIT
- AlicenseNot gradedqualityCmaintenanceMCP tool server that gives any AI agent the ability to search, scrape, and analyze content across the internet.42MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for realtime X (Twitter) search enabling keyword/semantic search, filters, date ranges, and citations for coding agents.3 npmMIT
- AlicenseNot gradedqualityCmaintenanceLive X/Twitter and Reddit research. 10 read-only MCP tools, Google/GitHub sign-in. Free tier.2MIT