reddit-radar-mcp

Find Reddit threads where your product genuinely fits, reconstruct the conversation, and gate every drafted reply against a claim boundary you define.

Read-only by design. There is no code path that posts, votes, or acts as an account, and a test asserts there never will be. Drafts are for a human to review, edit, and post.

npx reddit-radar-mcp          # run as an MCP server
npm install reddit-radar-mcp  # or use the scoring/gate functions directly

Requires Node 20.10+. No build step, no native dependencies.

Why this exists

The usual "social listening" tool finds mentions. That is the easy half. The hard half is everything after: is this thread actually relevant, what is the person really asking, and is the reply you are about to post true?

This package is built around three claims that came out of running it in production:

1. Keyword matching produces mostly garbage. A recency + question-form + "any recommendations" heuristic scores 50/100 on literally any recent Reddit post. The fix is the anchor rule (below), and it is the most important thing here.

2. Where a thread lives changes what you should say. The same question in a buyer subreddit and an engineering subreddit warrant different comments, so subreddit tiers set behaviour, not just ranking.

3. A model writing promotional copy is the worst possible judge of whether it overclaimed. So the claim gate is deterministic, rule-based, and runs server-side. It refuses to hand back a blocked draft.

Quick start

Write a config:

Name it .mjs unless your project already sets "type": "module" — otherwise Node parses it as CommonJS and the import fails.

// radar.config.mjs
import { defineConfig, packs, composePacks } from 'reddit-radar-mcp';

export default defineConfig({
  product: {
    name: 'Acme',
    what: 'CI/CD pipeline observability.',
    claims: ['flaky test detection', 'build timing breakdowns'],
  },

  queries: ['flaky tests', 'CI pipeline slow', 'build times'],

  // REQUIRED. Without it, every recent question looks like an opportunity.
  domainTerms: ['ci', 'pipeline', 'flaky', 'github actions', 'test suite'],

  // Words that mean something else outside your niche.
  ambiguousTerms: ['build', 'runner'],

  tiers: {
    tier1: { mode: 'PROMOTE',        weight: 20, subreddits: ['devops'] },
    tier2: { mode: 'PROMOTE_SOFT',   weight: 15, subreddits: ['sre', 'kubernetes'] },
    tier3: { mode: 'CONTRIBUTE',     weight: 8,  subreddits: ['ExperiencedDevs'] },
    tier4: { mode: 'TECHNICAL_ONLY', weight: 3,  subreddits: ['programming'] },
  },

  gate: {
    ...composePacks(packs.noPricing, packs.noFabricatedMetrics, packs.noCustomerNames),
    productPattern: /\bAcme\b/i,
    unsupported: [
      { term: /\bJenkins\b/i, why: 'No Jenkins integration exists.' },
    ],
  },
});

Register it as an MCP server:

claude mcp add radar --scope user \
  -e RADAR_CONFIG=/abs/path/radar.config.mjs \
  -- npx reddit-radar-mcp

Then just talk to your agent: "run a sweep and show me what's worth replying to."

The anchor rule

The single most useful idea in this package.

A post is anchored only if something ties it to your domain: real domain vocabulary, an unambiguous query match, or a configured subreddit. Signals that describe the shape of a post — it is recent, it is a question, it says "recommendations" — can never carry a post on their own.

Without this gate, those shape signals sum to 40+ and pass anything. With it, a post in r/podcasts asking about a "POD episode" stops outranking a genuine buying question.

Two related behaviours fall out of the same idea:

• Ambiguous terms ("build", "POD", "detention") only count when a second domain signal is present — or when the post is in one of your subreddits, since the subreddit is itself domain context.

• Venting is penalized hard (-35). Rants out-engage buying questions, so without this the ranking inverts and you get "opportunities" that are people complaining about their coworkers.

Engagement modes

Tiers attach a mode to every result, and the sweep output repeats it next to each thread:

The draft gate

check_draft runs two independent checks and refuses to return a blocked draft.

Claim gate (factCheck) — deterministic rules over your claim boundary. Starter packs cover the four common failure modes:

Two behaviours worth knowing:

• Denials are always allowed. "We do not support Jenkins" passes. An early version blocked it, which pushed drafts toward silence about gaps — the opposite of the intent. Conceding a real limitation is the cheapest credibility available.

• Capability checks are assertion-scoped. "Jenkins is a solid choice if you need self-hosting" does not trip the gate, because it is not a claim about your product.

Quality gate (styleCheck) — catches text that reads as unedited generated filler: em dashes, semicolons, curly quotes, negation framing ("not just X, it's Y"), marketing vocabulary, flat sentence rhythm, and thin substance.

This is not AI-detection evasion. It cannot be and does not try to be. Many subreddits ban low-effort content, and moderators read comments rather than running classifiers. So the gate enforces what that rule actually asks for: real substance, no filler. The human still edits and posts, and disclosure is always present.

Pass your domain vocabulary so the substance check knows what a specific noun looks like:

styleCheck(draft, { anchorTerms: [...config.domainTerms, ...config.featureTerms] });

MCP tools

Every tool is deterministic. The model supplies the writing; the server supplies the facts and the veto.

Reddit access

Three interchangeable adapters behind one interface:

• BrowserRedditClient — reads the same public pages a person reads, from your own browser tool. No credentials. This is the default path today.

• RedditApiClient — OAuth against the official Data API. Access is approval-gated; see docs/REDDIT-ACCESS.md.

• FixtureRedditClient — local JSON fixtures for tests and development.

Fixtures run through the same normalizers as live responses, so parsers are genuinely exercised rather than first meeting real data in production.

A caveat worth stating plainly: browser mode depends on Reddit's DOM, and Reddit ships redesigns. The extractors are written to fail loudly rather than silently return empty threads that look like "no discussion found."

Programmatic use

import { scoreRelevance, factCheck, styleCheck, packs, composePacks } from 'reddit-radar-mcp';
import config from './radar.config.js';

const result = scoreRelevance(post, config, { matchedQueries: ['flaky tests'] });
if (result.passed) console.log(result.score, result.reasons);

const gate = factCheck(draft, config.gate);
if (!gate.allowed) console.log(gate.findings);

Ethics and policy

This tool exists to help you find conversations you can genuinely contribute to. It will not help you astroturf.

• No posting automation. Not implemented, and enforced by test.

• Disclose affiliation. requireDisclosure is on by default. Undisclosed vendor comments get removed and can earn a permanent ban, which ends the channel entirely.

• One account. Reddit's Responsible Builder Policy prohibits registering multiple accounts for the same use case. Do not use this to run a sockpuppet network.

• Threads are scored, never people. Nothing here profiles an author, in line with Reddit's prohibition on inferring user characteristics.

• Respect subreddit rules. TECHNICAL_ONLY exists because pitching in the wrong place is both rude and counterproductive.

Environment variables

Full annotated list in .env.example.

Logs go to stderr only. On stdio transport stdout carries the JSON-RPC protocol, so anything written there corrupts the stream. Credentials in URLs and sensitive keys are redacted before logging.

Troubleshooting

Everything scores as an opportunity. Your domainTerms are too generic or missing. That list is what anchors a post to your domain, and without it the shape signals carry posts on their own. Config validation treats an empty list as an error for this reason.

Nothing scores at all. Check that domainTerms uses words that actually appear in post titles. Terms of 5+ characters match simple inflections (pipeline → pipelines); shorter ones match exactly, so app will not match apps.

A good draft is blocked as thin substance. Pass your vocabulary as anchorTerms — the MCP server does this from your config automatically, but a direct styleCheck() call needs it explicitly.

An honest limitation is blocked. It should not be; denials are explicitly allowed. Please report it.

Reddit shows "Prove your humanity". A cold search can hit a JS challenge. Loading any subreddit page first usually clears it for the session.

"Cannot use import statement outside a module". Your config is a .js file in a project without "type": "module", so Node parses it as CommonJS. Either name it radar.config.mjs or add "type": "module" to the nearest package.json. A .json config avoids the question entirely, at the cost of regex literals and composePacks.

More in SUPPORT.md.

Tests

npm test       # 33 unit tests
npm run smoke  # 14 checks over the real MCP wire protocol
npm run verify # everything, including the metadata consistency guard

The safety suite asserts that no client exposes a write method, no source file references a Reddit write endpoint, and the package exports no posting function.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Note the permanent exclusions listed there: posting automation, multi-account support, and AI-detection evasion are deliberate non-goals rather than missing features.

• Changelog

• Security policy

• Support

Support this project

If this saves you time, sponsoring on GitHub helps keep it maintained. Entirely optional — the package is MIT and always will be.

Non-financial contributions are just as useful: a bug report with a reproducing config, a rule pack that generalizes, or a note about a scoring case that surprised you.

License

MIT — see LICENSE.