reddit-growth-mcp

<p align="center">
  <img src="assets/banner.png" alt="Reddit Growth MCP" width="480" />
</p>

<h1 align="center">Reddit Growth MCP</h1>

[![PyPI](https://img.shields.io/pypi/v/reddit-growth-mcp)](https://pypi.org/project/reddit-growth-mcp/)
[![CI](https://github.com/latent-9/reddit-growth-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/latent-9/reddit-growth-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A toolkit for analyzing subreddits and the patterns behind posts that get
accepted and perform well. It helps you choose the right communities and shape
posts that fit each one, using real data rather than guesswork.

It runs as an MCP server (for use inside Claude, Cursor, and other MCP clients)
and as a standalone command-line tool. Most analysis works without any Reddit
API credentials, because it reads from a public historical archive.

<p align="center">
  <img src="assets/demo-plan.png" alt="reddit-growth in action" width="760" />
</p>

One command turns a list of subreddits into a plan — where to post, what to
post, and when:

```text
$ reddit-growth plan singularity LocalLLaMA mcp --tz 7

GROWTH PLAN
Target: r/singularity
  growth 222.9 · viral 629.1 · 48 posts/day · 23 comments · 12% removed (safe)
  discussion depth (insight): medium (30% substantive)

Also worth posting to (safe, tailor per sub)
  r/LocalLLaMA   growth 64.3 · 12% removed (safe)

What to post (viral recipe)
  Format : image      Flair : AI      Length : ~97 chars, no clickbait
  Words  : open, kimi, deepseek

When to post
  08:00 UTC = 15:00 local / 15:00 UTC = 22:00 local   ·   Days: Friday, Saturday
```

## Quick start

Requirements: Python 3.11+ and [uv](https://docs.astral.sh/uv/). No Reddit
account or API keys are needed to get started.

Install from PyPI:

```bash
uvx reddit-growth-mcp                            # run the MCP server instantly
pipx install reddit-growth-mcp                   # or install the CLI + server
reddit-growth plan singularity LocalLLaMA mcp    # your first growth plan
```

Or from a clone (for development):

```bash
uv sync                                                    # install dependencies
uv run python -m src.cli plan singularity LocalLLaMA mcp   # your first growth plan
```

That prints where to post, what to post, and when — using only the public
archive. Every command has the form `uv run python -m src.cli <command> [options]`
(shown throughout as `reddit-growth <command>`, which is the installed alias).
Add `-h` to any command for help, e.g. `uv run python -m src.cli plan -h`.

### Interactive launcher

Prefer a menu to flags? Run:

```bash
bash scripts/menu.sh
```

Pick a mode (plan, compare, patterns, draft, …), choose subreddits from a
searchable preset list, and it runs the command for you — all in one window.
With [gum](https://github.com/charmbracelet/gum) installed you get an arrow-key
TUI with fuzzy search; otherwise it falls back to a numbered menu. Type `h` for
a built-in guide.

## What it answers

- Which subreddits fit my topic, and how much reach do they have?
- Will my post survive here, or does this community remove a lot of posts?
- What actually performs here: which format, title style, timing, and flair?
- Given a specific draft, how is it likely to do, and how do I improve it?

## Demo

`compare` ranks candidate subreddits by growth, viral ceiling, and removal risk:

![compare mode](assets/demo-compare.png)

## Tools

| Tool | Purpose | Needs credentials |
| --- | --- | --- |
| `analyze_post_patterns` | What performs in a sub: timing, media, title style, flair, keywords, by a configurable metric | No |
| `analyze_acceptance` | Removal rate and what tends to get removed; official rules when credentials are present | No |
| `compare_subreddits` | Rank subreddits by growth (typical reach + viral upside), with traffic (posts/day), discussion, removal risk, and a safety label; `rank_by` switches to viral/opportunity/insight | No |
| `analyze_insight` | Discussion depth (comment substance) plus a heuristic sentiment read (supportive/mixed/critical) — not just comment count | No |
| `growth_plan` | One call: safest strong target, cross-post options, viral recipe, and best posting times | No |
| `evaluate_draft` | Predict a draft's performance (0-100) and acceptance risk, with drivers and fixes | No |
| `evaluate_draft_across` | Score one draft across subs, ranked by size-fair fit (percentile) vs raw reach | No |
| `analyze_subreddit` | Estimate a subreddit's activity (posts/day); uses the archive without credentials | No |
| `find_target_subreddits_tool` | Discover and rank subreddits for topics by estimated traffic | Yes |
| `fetch_posts`, `fetch_multiple`, `search_subreddit`, `fetch_comments` | Raw data access | Yes |

The analysis tools are subreddit-agnostic — they work on any archived sub. The
launcher ships 40+ presets across AI, dev, and startup communities (`ChatGPT`,
`DeepSeek`, `LocalLLaMA`, `StableDiffusion`, `SaaS`, `indiehackers`, …).

## Data sources

- PRAW for live Reddit access (read-only). Requires API credentials.
- Arctic Shift (https://github.com/ArthurHeitmann/arctic_shift), a public
  historical archive and the successor to Pushshift. Requires no credentials.

Removal detection follows the reveddit approach: the archive records what was
posted, and moderator removals are read from that record. When Reddit
credentials are available, `analyze_acceptance` performs an accurate live diff
(archive vs. current Reddit) to resolve ambiguous cases; without credentials it
runs archive-only and flags its confidence.

## Reddit credentials (optional)

Everything above works with no account. Credentials only unlock the
credential-only tools (raw data access, `find_target_subreddits`) and the
accurate live-removal check. Create a "script" app at
https://www.reddit.com/prefs/apps, then:

```bash
cp .env.sample .env
# REDDIT_CLIENT_ID=...
# REDDIT_CLIENT_SECRET=...
# REDDIT_USER_AGENT=reddit-growth-mcp/0.2 by u/your_username
```

## Command-line usage

Every command runs credential-free from the archive. The commands are:
`traffic`, `insight`, `patterns`, `acceptance`, `compare`, `plan`, `report`,
`draft`, and `fit` (run `-h` on any of them for options).

```bash
uv run python -m src.cli traffic LocalLLaMA
uv run python -m src.cli insight mcp
uv run python -m src.cli patterns Fedora --time month
uv run python -m src.cli patterns commandline --metric discussion
uv run python -m src.cli acceptance technology
uv run python -m src.cli compare Fedora gnome linux
uv run python -m src.cli plan singularity LocalLLaMA mcp --tz 7
uv run python -m src.cli draft ClaudeAI --title "I built an ASCII art tool" --type image
uv run python -m src.cli fit singularity LocalLLaMA mcp --title "..." --type video
```

`fit` scores one draft across several subreddits and ranks by a size-fair fit
(the draft's percentile within each sub's own score distribution) alongside raw
expected reach, so a small sub where the post lands in the top decile isn't
buried by a big sub's larger absolute numbers.

Add `--json` to any command for raw output.

Time-based commands (`patterns`, `plan`, `draft`, `fit`, `report`) accept
`--time day|week|month|year|all` — shorter is fresher but a smaller sample.

`patterns` accepts `--metric`:

- `score`: upvotes (reach).
- `comments`: comment volume.
- `discussion`: comments per upvote, a proxy for genuine engagement rather than
  drive-by upvotes.
- `quality`: upvotes damped by a clickbait penalty.

## Example analysis

Ranking a set of AI/dev communities for account growth (credential-free):

```
$ reddit-growth compare singularity LocalLLaMA unixporn linux mcp --window 30d

SUBREDDIT COMPARISON  (ranked by growth)
subreddit             growth   viral  posts/day  comments  removal    safety  conf
  r/singularity         222.9   629.1       48.7        22     12%      safe  ok
  r/LocalLLaMA           64.3   199.8       80.2        19     12%      safe  ok
  r/unixporn             53.4   120.0       38.5         2     28%  moderate  ok
  r/linux                12.8    42.6       60.9        10     55%    strict  ok
  r/mcp                   1.5     2.8       45.6         1     30%  moderate  ok
```

Reading it: r/singularity and r/LocalLLaMA are safe (low removal) and active,
with high viral ceilings and real discussion; r/linux is active but strict
(55% of posts removed). Turning that into a plan:

```
$ reddit-growth plan singularity LocalLLaMA unixporn mcp --tz 7

GROWTH PLAN
Target: r/singularity
  growth 222.9 · viral 629.1 · 48.7 posts/day · 22 comments · 12% removed (safe)

Also worth posting to (safe, tailor per sub)
  r/LocalLLaMA   growth 64.3 · 12% removed (safe)
  r/unixporn     growth 53.4 · 28% removed (moderate)

What to post (viral recipe)
  Format : link
  Flair  : AI
  Length : ~97.5 chars, no clickbait

When to post
  08:00 UTC = 15:00 local / 15:00 UTC = 22:00 local
  Days: Saturday, Friday
```

Figures are estimates from a sample and will shift over time; run it live for
current numbers.

## Use as an MCP server

Register the server once (Claude Code shown):

```bash
claude mcp add reddit-growth-mcp -- uvx reddit-growth-mcp
```

For Cline, Cursor, Claude Desktop, and other clients, add it to the MCP
settings JSON (no separate install — `uvx` fetches it from PyPI):

```json
{
  "mcpServers": {
    "reddit-growth": {
      "command": "uvx",
      "args": ["reddit-growth-mcp"]
    }
  }
}
```

Then ask in natural language, for example "analyze what performs in r/Fedora"
or "will this title get accepted in r/linux?" The client calls the tools.

For the full flow in one step, ask for a growth plan ("build a growth plan for
r/singularity, r/LocalLLaMA, r/mcp") to invoke `growth_plan`, or select the
`reddit_growth` prompt, which guides the assistant through finding a safe
high-traffic subreddit and crafting a post that fits its viral recipe.

To run the server directly over stdio: