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.

Related MCP server: @cyanheads/hn-mcp-server

Tools

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)

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:

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