{
  "markdown": "<h1 align=\"center\">Reddit Growth MCP</h1>\n\n<p align=\"center\">\n  <strong>Find where to post, learn each subreddit's viral recipe, and score your draft before you publish — no Reddit API key required.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/reddit-growth-mcp/\"><img src=\"https://img.shields.io/pypi/v/reddit-growth-mcp\" alt=\"PyPI\" /></a>\n  <a href=\"https://github.com/latent-9/reddit-growth-mcp/actions/workflows/ci.yml\"><img src=\"https://github.com/latent-9/reddit-growth-mcp/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /></a>\n  <a href=\"https://glama.ai/mcp/servers/latent-9/reddit-growth-mcp\"><img src=\"https://glama.ai/mcp/servers/latent-9/reddit-growth-mcp/badges/score.svg\" alt=\"Glama quality score\" /></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"reddit-growth in action — plan where to post, score a draft, and compare subreddits\" width=\"820\" />\n</p>\n\n<p align=\"center\">\n  <em>One command each: <code>plan</code> where to post, <code>draft</code> to score a post before you publish, and <code>compare</code> to rank subreddits by removal risk.</em>\n</p>\n\n<p align=\"center\">\n  <a href=\"assets/reddit-growth-demo.mp4\"><strong>▶ Watch the full-quality 30s MP4</strong></a>\n</p>\n\nReddit Growth MCP turns a list of subreddits into a plan — **where** to post,\n**what** to post, and **when** — by reading each community's format, flair,\ntiming, and keyword recipe from a public historical archive. The whole core\nworkflow runs with no account or API key. It works as an MCP server (for Claude,\nCursor, and other MCP clients) and as a standalone command-line tool.\n\n> **Built by a [Top 1% Poster in r/ClaudeAI](https://www.reddit.com/user/Oliveaniss_/)** — the\n> heuristics here encode what actually gets upvoted and what gets removed, not guesswork.\n\n<p align=\"center\">\n  <img src=\"assets/proof-claudeai.png\" alt=\"Top 1% Poster in r/ClaudeAI (Legendary)\" width=\"820\" />\n</p>\n\n## Quick start\n\nRequirements: Python 3.11+ and [uv](https://docs.astral.sh/uv/). No Reddit\naccount or API keys are needed to get started.\n\nInstall from PyPI:\n\n```bash\nuvx reddit-growth-mcp                            # run the MCP server instantly\npipx install reddit-growth-mcp                   # or install the CLI + server\nreddit-growth plan singularity LocalLLaMA mcp    # your first growth plan\n```\n\nOr from a clone (for development):\n\n```bash\nuv sync                                                    # install dependencies\nuv run python -m src.cli plan singularity LocalLLaMA mcp   # your first growth plan\n```\n\nThat prints where to post, what to post, and when — using only the public\narchive. Every command has the form `uv run python -m src.cli <command> [options]`\n(shown throughout as `reddit-growth <command>`, which is the installed alias).\nAdd `-h` to any command for help, e.g. `uv run python -m src.cli plan -h`.\n\nIf you activate the virtualenv directly (`source .venv/bin/activate`) and zsh\nstill reports `command not found: reddit-growth`, run `rehash` — zsh caches\ncommand locations at startup and needs a nudge after the venv is added to PATH.\nOpening a new terminal also works, or call the binary by path without activating:\n`.venv/bin/reddit-growth plan singularity LocalLLaMA mcp`.\n\n### Interactive launcher\n\nPrefer a menu to flags? Run:\n\n```bash\nbash scripts/menu.sh\n```\n\nPick a mode (plan, compare, patterns, draft, …), choose subreddits from a\nsearchable preset list, and it runs the command for you — all in one window.\nWith [gum](https://github.com/charmbracelet/gum) installed you get an arrow-key\nTUI with fuzzy search; otherwise it falls back to a numbered menu. Type `h` for\na built-in guide.\n\n## What it answers\n\n- Which subreddits fit my topic, and how much reach do they have?\n- Will my post survive here, or does this community remove a lot of posts?\n- What actually performs here: which format, title style, timing, and flair?\n- Given a specific draft, how is it likely to do, and how do I improve it?\n\n## See it work\n\n`compare` ranks candidate subreddits by growth, viral ceiling, discussion, and\nremoval risk — so you post where you'll be seen and skip communities that remove\nmost submissions (note r/ClaudeAI below: 96% removed, strict):\n\n![compare mode](assets/demo-compare.png)\n\n`patterns` reads one community's viral recipe — the media types, hours, days,\nflairs, and keywords that actually perform, ranked by median so a single lucky\npost can't crown a category:\n\n![patterns mode](assets/demo-patterns.png)\n\nFigures are live estimates from a sample and shift over time — run the commands\nyourself for current numbers.\n\n## Tools\n\n| Tool | Purpose | Needs credentials |\n| --- | --- | --- |\n| `analyze_post_patterns` | What performs in a sub: timing, media, title style, flair, keywords, by a configurable metric | No |\n| `analyze_acceptance` | Removal rate and what tends to get removed; official rules when credentials are present | No |\n| `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 |\n| `analyze_insight` | Discussion depth (comment substance) plus a heuristic sentiment read (supportive/mixed/critical) — not just comment count | No |\n| `growth_plan` | One call: safest strong target, cross-post options, viral recipe, and best posting times | No |\n| `evaluate_draft` | Predict a draft's performance (0-100) and acceptance risk, with drivers and fixes | No |\n| `evaluate_draft_across` | Score one draft across subs, ranked by size-fair fit (percentile) vs raw reach | No |\n| `analyze_subreddit` | Estimate a subreddit's activity (posts/day); uses the archive without credentials | No |\n| `find_target_subreddits_tool` | Discover and rank subreddits for topics by estimated traffic | Yes |\n| `fetch_posts`, `fetch_multiple`, `search_subreddit`, `fetch_comments` | Raw data access | Yes |\n\nThe analysis tools are subreddit-agnostic — they work on any archived sub. The\nlauncher ships 40+ presets across AI, dev, and startup communities (`ChatGPT`,\n`DeepSeek`, `LocalLLaMA`, `StableDiffusion`, `SaaS`, `indiehackers`, …).\n\n## Data sources\n\n- PRAW for live Reddit access (read-only). Requires API credentials.\n- Arctic Shift (https://github.com/ArthurHeitmann/arctic_shift), a public\n  historical archive and the successor to Pushshift. Requires no credentials.\n\nRemoval detection follows the reveddit approach: the archive records what was\nposted, and moderator removals are read from that record. When Reddit\ncredentials are available, `analyze_acceptance` performs an accurate live diff\n(archive vs. current Reddit) to resolve ambiguous cases; without credentials it\nruns archive-only and flags its confidence.\n\n## Reddit credentials (optional)\n\nEverything above works with no account. Credentials only unlock the\ncredential-only tools (raw data access, `find_target_subreddits_tool`) and the\naccurate live-removal check. Create a \"script\" app at\nhttps://www.reddit.com/prefs/apps, then:\n\n```bash\ncp .env.sample .env\n# REDDIT_CLIENT_ID=...\n# REDDIT_CLIENT_SECRET=...\n# REDDIT_USER_AGENT=reddit-growth-mcp/0.2.1 by u/your_username\n```\n\n## Command-line usage\n\nEvery command runs credential-free from the archive. The commands are:\n`traffic`, `insight`, `patterns`, `acceptance`, `compare`, `plan`, `report`,\n`draft`, and `fit` (run `-h` on any of them for options).\n\n```bash\nuv run python -m src.cli traffic LocalLLaMA\nuv run python -m src.cli insight mcp\nuv run python -m src.cli patterns Fedora --time month\nuv run python -m src.cli patterns commandline --metric discussion\nuv run python -m src.cli acceptance technology\nuv run python -m src.cli compare Fedora gnome linux\nuv run python -m src.cli plan singularity LocalLLaMA mcp --tz 7\nuv run python -m src.cli draft ClaudeAI --title \"I built an ASCII art tool\" --type image\nuv run python -m src.cli fit singularity LocalLLaMA mcp --title \"...\" --type video\n```\n\n`fit` scores one draft across several subreddits and ranks by a size-fair fit\n(the draft's percentile within each sub's own score distribution) alongside raw\nexpected reach, so a small sub where the post lands in the top decile isn't\nburied by a big sub's larger absolute numbers.\n\nAdd `--json` to any command for raw output.\n\nTime-based commands (`patterns`, `plan`, `draft`, `fit`, `report`) accept\n`--time day|week|month|year|all` — shorter is fresher but a smaller sample.\n\n`patterns` accepts `--metric`:\n\n- `score`: upvotes (reach).\n- `comments`: comment volume.\n- `discussion`: comments per upvote, a proxy for genuine engagement rather than\n  drive-by upvotes.\n- `quality`: upvotes damped by a clickbait penalty.\n\n## Use as an MCP server\n\nRegister the server once (Claude Code shown):\n\n```bash\nclaude mcp add reddit-growth-mcp -- uvx reddit-growth-mcp\n```\n\nFor Cline, Cursor, Claude Desktop, and other clients, add it to the MCP\nsettings JSON (no separate install — `uvx` fetches it from PyPI):\n\n```json\n{\n  \"mcpServers\": {\n    \"reddit-growth\": {\n      \"command\": \"uvx\",\n      \"args\": [\"reddit-growth-mcp\"]\n    }\n  }\n}\n```\n\nThen ask in natural language, for example \"analyze what performs in r/Fedora\"\nor \"will this title get accepted in r/linux?\" The client calls the tools.\n\nFor the full flow in one step, ask for a growth plan (\"build a growth plan for\nr/singularity, r/LocalLLaMA, r/mcp\") to invoke `growth_plan`, or select the\n`reddit_growth` prompt, which guides the assistant through finding a safe\nhigh-traffic subreddit and crafting a post that fits its viral recipe.\n\nTo run the server directly over stdio:\n\n```bash\nuv run python -m src.server\n```\n\n### Docker\n\nThe server also ships as a container (stdio transport):\n\n```bash\ndocker build -t reddit-growth-mcp .\ndocker run -i --rm reddit-growth-mcp\n# with credentials:\ndocker run -i --rm -e REDDIT_CLIENT_ID=... -e REDDIT_CLIENT_SECRET=... reddit-growth-mcp\n```\n\n## Targeting workflow\n\nTo find where to post for growth, `compare_subreddits` reports, per subreddit:\n\n- viral potential (90th-percentile reach adjusted for removal risk) and ceiling,\n- posts per day (a credential-free traffic proxy),\n- typical discussion (median comments),\n- removal rate and a safety label (safe / moderate / strict), so you can avoid\n  communities that remove most posts.\n\nA typical flow: `compare` to shortlist safe, high-traffic, high-ceiling subs,\nthen `patterns` to read the viral recipe, then `evaluate_draft` to score a draft\nagainst it before posting.\n\nReach and insight are different goals. `compare` counts comments (volume);\n`analyze_insight` measures their *depth* — median comment length and the share\nof substantive comments. A sub can have many short one-line replies (high volume,\nlow insight) or fewer long technical comments (low volume, high insight). Use\nreach-oriented ranking for visibility, and `analyze_insight` to find where\nthoughtful discussion happens and reputation is built.\n\n## Accuracy and methodology\n\nThe tool is built to avoid the common failure modes of naive Reddit analytics.\n\n- Robust central tendency. Categories (media, flair, time) are ranked by the\n  median, with the mean shown for reference, so a single viral post cannot crown\n  a category.\n- Minimum-sample gating. A category or time bucket must contain enough posts to\n  be reported as \"best\". Small buckets are not treated as reliable signals, and\n  draft scoring ignores title signals whose with/without groups are too small,\n  so a single lucky post cannot swing a projection or seed a bogus suggestion.\n- Confidence labelling. Each pattern report states a confidence level based on\n  its sample size, and each acceptance report states a reliability level.\n- Settled scores. Archived scores stabilise after roughly 36 hours, so analysis\n  excludes the most recent two days.\n- AutoMod awareness. Posts that were only AutoMod-filtered at capture time are\n  treated as uncertain, not confirmed removals, because they are frequently\n  approved later. On AutoMod-heavy subreddits this is flagged, and an accurate\n  live check requires credentials.\n- Removal-aware verdicts. A draft's acceptance verdict folds in the sub's base\n  removal rate, so a compliant post in a subreddit that removes most of what it\n  gets is flagged risky rather than \"likely accepted\".\n- Anti-clickbait. Clickbait titles are detected (hype phrases, shouted words,\n  emoji and punctuation spam), and each report states whether the community\n  actually rewards or penalises clickbait, so guidance never pushes you toward\n  it. `evaluate_draft` penalises a clickbaity draft only where the sub dislikes\n  it.\n\n## Limitations\n\n- Traffic figures are estimates. Reddit does not expose true daily visitor\n  counts through its public API.\n- Findings are correlations from a sample, not Reddit's ranking algorithm and\n  not a guarantee of performance.\n- AutoModerator configuration is private. Karma and account-age gates are\n  inferred from rule text and require credentials to read.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run pytest -q                       # tests\nuv run ruff check src tests            # lint\nuv run ruff format src tests           # format\n```\n\nCI runs the lint, format check, and tests on every push and pull request.\n\nThe analysis logic lives in `src/analysis/` (traffic, acceptance, patterns,\ndraft, compare, arctic, helpers). The MCP surface is `src/server.py` and the\nCLI is `src/cli.py`.\n\n## License\n\nMIT\n\n<sub>mcp-name: io.github.latent-9/reddit-growth-mcp</sub>\n",
  "bytes": 13568,
  "sha": "46c00e61c331f0a434c1c0daa7fa46665dfd45fbe1f0b01ef149719424ce686c",
  "repo_slug": "latent-9/reddit-growth-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_latent_9_reddit_growth_mcp_766d2d98/readme"
}