supragents-mcp

A read-only research MCP server: Hacker News, Reddit, and Product Hunt in one npx command. It works with zero API keys, Hacker News and Reddit's public search both work out of the box. Add a free Reddit app for heavier Reddit use, or a Product Hunt developer token to unlock producthunt_top.

No tracking, no accounts required to start, no dependencies beyond the MCP SDK and zod, everything else uses Node's built-in fetch.

Install

Nothing to install by hand, npx fetches it on first use. Add it to your project's .mcp.json:

{
  "mcpServers": {
    "supragents": {
      "command": "npx",
      "args": ["-y", "supragents-mcp"]
    }
  }
}

Restart Claude Code (or start a fresh session) and the tools below are available immediately, no keys needed for Hacker News or basic Reddit use.

Tools

Tool	Params	What it does
hn_search	query (required), limit? (1-25, default 10)	Search Hacker News stories by relevance via the Algolia HN Search API.
hn_front_page	limit? (1-25, default 15)	Get the current Hacker News front page.
hn_thread	id (required), max_comments? (1-25, default 20)	Get a story and its top comments, flattened, HTML stripped.
reddit_search	query (required), subreddit?, sort? (relevance/hot/top/new/comments), limit? (1-25, default 15)	Search Reddit posts by keyword, optionally scoped to a subreddit.
reddit_top	subreddit (required), timeframe? (hour/day/week/month/year/all, default week), limit? (1-25, default 15)	Top posts from a subreddit over a timeframe.
reddit_comments	post_url_or_id (required), limit? (1-25, default 20)	A post plus its top-level comments, by URL or id.
producthunt_top	topic?, limit? (1-25, default 10)	Top Product Hunt posts, optionally by topic. Requires PRODUCTHUNT_ACCESS_TOKEN.
market_research	topic (required), limit_per_source? (1-25, default 10)	Runs hn_search + reddit_search (+ producthunt_top if configured) in parallel, merges results tagged by source, sorted by engagement. Returns sources_used and sources_skipped, a failure in one source never fails the whole call.

Every result is capped at 25 items, and any HTML in text fields (comment bodies, selftext, titles) is stripped to plain text before it's returned.

Environment variables (all optional)

Variable	Unlocks	How to get it
REDDIT_CLIENT_ID + REDDIT_CLIENT_SECRET	Reliable Reddit access via OAuth (app-only, no user login). Without these, Reddit tools fall back to the public .json endpoints, which Reddit sometimes rate-limits.	reddit.com/prefs/apps: create a "script" app, copy the client id and secret.
PRODUCTHUNT_ACCESS_TOKEN	producthunt_top (and Product Hunt's slice of market_research)	producthunt.com/v2/oauth/applications: create an application, generate a Developer Token.

If a Reddit call hits a public-endpoint block (HTTP 403/429), the tool returns an error result with the exact setup steps above instead of failing silently. If PRODUCTHUNT_ACCESS_TOKEN is missing, producthunt_top returns a helpful error pointing back here instead of a raw 401.

Example with all env vars set

{
  "mcpServers": {
    "supragents": {
      "command": "npx",
      "args": ["-y", "supragents-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your-client-id",
        "REDDIT_CLIENT_SECRET": "your-client-secret",
        "PRODUCTHUNT_ACCESS_TOKEN": "your-developer-token"
      }
    }
  }
}

REST mode (--serve)

MCP over stdio is the primary interface, that's what Claude Code speaks and what the sections above assume. --serve is a separate mode for everything outside Claude Code: shell scripts, cron jobs, n8n, or any other tool that wants to call these same tools over plain HTTP instead.

npx supragents-mcp --serve        # binds 127.0.0.1:8787
npx supragents-mcp --serve 9000   # custom port

It exposes the exact same 8 tools, same handlers, same env vars, just over HTTP instead of stdio:

Route	What it does
GET /health	{ status, name, version, tools }
GET /tools	Lists every tool with its title, description, and JSON Schema for its arguments
POST /tools/{name}	Calls a tool. JSON body is the tool's arguments (e.g. {"query": "claude code"} for hn_search). Returns the tool's JSON result on success, or a JSON error body on failure

curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/tools
curl -X POST http://127.0.0.1:8787/tools/hn_search \
  -H 'content-type: application/json' \
  -d '{"query": "claude code"}'

Binds to 127.0.0.1 by default, not 0.0.0.0, so it's not reachable from outside your machine unless you put something in front of it on purpose.

Development

npm install
npm test

Tests are pure unit tests over the URL builders, HTML stripping, the Reddit OAuth/public fallback decision, and the market_research merge logic (all with injected fetchers, no live network calls), one test that spawns the server binary and does a real MCP initialize + tools/list round trip over stdio, and REST-mode tests covering route parsing, the unknown-tool 404, and one end-to-end spawn of --serve against an ephemeral port.

License

MIT