# reddit-leads-mcp

An [MCP](https://modelcontextprotocol.io) server that turns Claude (or any MCP client) into a Reddit lead-finding agent: search for buying-intent conversations, score them against your product, and read full threads before drafting a reply.

Extracted from the scoring pipeline behind [RedProwler](https://github.com/thetomtoro/RedProwler).

## Tools

| Tool | What it does |
|---|---|
| `search_reddit` | Search recent posts by query, optionally restricted to subreddits |
| `score_leads` | Two-phase lead scoring: lexical pre-score on every post, Claude semantic scoring for posts that clear the threshold |
| `fetch_thread` | Fetch a post with its top comments for full context |

A typical session: "search r/SaaS and r/startups for people asking about churn tools, score them against my product, and show me the top three threads."

## Why two-phase scoring

Sending every scraped post to an LLM is slow and expensive, and most posts are obviously irrelevant. The pre-score is a lexical pass (keyword coverage plus buying-intent phrasing like "looking for", "alternative to", "willing to pay") capped at 0.5. Only posts above an escalation threshold get a Claude call, which returns a 0 to 1 semantic score behind strict JSON extraction and range clamping. If the API is down or returns something unparseable, the post keeps its pre-score instead of failing the run. In RedProwler this design cut scoring costs roughly in half with no measurable recall loss.

Without an `ANTHROPIC_API_KEY`, the server still works: everything is ranked by pre-score alone.

## Setup

Requires Node 18+.

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "reddit-leads": {
      "command": "npx",
      "args": ["-y", "github:thetomtoro/reddit-leads-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "...",
        "REDDIT_CLIENT_SECRET": "...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

Reddit credentials come from a free "script" app at [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps); the server uses the client-credentials grant against `oauth.reddit.com`. Without them it falls back to the public JSON endpoints, which Reddit rejects from many networks these days, so credentials are recommended. `ANTHROPIC_API_KEY` is optional; omit it to run lexical-only scoring.

### From source

```bash
git clone https://github.com/thetomtoro/reddit-leads-mcp
cd reddit-leads-mcp
npm install
npm run build
npm test
```

Point your MCP client at `node dist/index.js` over stdio.

## Notes

- Read-only. OAuth when credentials are set, public JSON otherwise, always with a descriptive User-Agent. Be polite with request volume; this is for finding conversations worth joining, not mass scraping.
- `REDDIT_LEADS_MODEL` overrides the scoring model (default: Claude Haiku).
- Scoring internals live in `src/scoring.ts` and are covered by unit tests that run fully offline.

## License

MIT