# Reddit MCP Scraper (`litezero/reddit-mcp-scraper`) Actor

Scrape Reddit posts, comments, user profiles, and subreddits without logging in. Features an unblockable Hybrid Stealth Engine to bypass Cloudflare 403s. Built-in AI summarization, deep multi-sort crawling, media downloads, and native MCP support for AI Agents!

- **URL**: https://apify.com/litezero/reddit-mcp-scraper.md
- **Developed by:** [LiteZero](https://apify.com/litezero) (community)
- **Categories:** AI, Developer tools, Social media
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.10 / 1,000 item scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Ultimate Reddit Scraper & MCP Server 🚀

A god-tier, highly optimized, unblockable Reddit web scraper built to bypass the 403 API limitations and extract deep insights, comment threads, and rich metadata. Designed specifically for AI Workflows, RAG systems, and data scientists.

### 🌟 Key Features

#### 1. Hybrid Stealth Engine (Unblockable)

Reddit actively blocks most generic API scrapers with `403 Forbidden` errors. This Actor completely bypasses Reddit's Cloudflare and bot-protection mechanisms by launching a headless **Playwright** browser to silently solve challenges and steal secure `reddit_session` cookies. It then passes those cookies into an ultra-fast HTTP crawler to scrape APIs at 50+ pages per second.

#### 2. Native AI Summarization & Sentiment (Phase 4)

Built-in LLM processing. Provide an `openaiApiKey` to automatically analyze posts on the fly. The Actor will natively output a `aiSummary` (1-sentence TL;DR) and a `sentiment` tag (Positive, Negative, Neutral, Toxic) for every post!

#### 3. User Profile Deep-Scraping (Phase 4)

Target specific users (e.g. `https://www.reddit.com/user/spez/`) to extract their entire post and comment history seamlessly into your dataset.

#### 4. Real-Time Webhooks (Phase 4)

Instantly forward every scraped post to Slack, Discord, or a custom API endpoint by providing a `webhookUrl`. Ideal for brand monitoring.

#### 5. Media Downloader (Phase 4)

Enable `downloadMedia` to physically download binary image (`.jpg`, `.png`, `.gif`) and video (`.mp4`) files directly to the Apify Key-Value Store instead of just linking them.

#### 6. Multi-Sort Deep Scraping

Reddit restricts list endpoints to a maximum of 1,000 items. To get more than 1,000 posts from a subreddit, this Actor utilizes a powerful **Multi-Sort Engine**. By enabling `all_sorts`, the Actor will seamlessly traverse through `hot`, `new`, `top (all time)`, `top (year)`, `top (month)`, and `top (week)`—effectively scraping up to **6,000+ posts per subreddit** in a single run.

#### 7. RAG-Optimized Markdown Export

Forget trying to parse deeply nested JSON comment trees into your LLM. When you enable `exportMarkdown`, this Actor stitches every post and its deeply threaded comments into a beautiful, hierarchical `.md` document. It is saved directly to your Apify Key-Value store under `RAG_EXPORT.md`, ready to be dropped straight into ChatGPT, Claude, Cursor, or LangChain.

#### 8. Authenticated Scraping (NSFW Access)

Reddit now strictly gates adult and quarantined communities behind a login wall. You can bypass this by simply passing your own logged-in `reddit_session` cookie into the secure input field. The Hybrid Stealth Engine will dynamically assume your identity to crawl gated content.

#### 9. PullPush Archive Fallback

Moderators and users delete valuable information constantly. The Actor has native integration with `api.pullpush.io`. If it detects `[deleted]` or `[removed]` content, it silently pings the archive to recover the original author and text!

#### 10. Native MCP Server Mode

This is not just a scraper; it's a **Model Context Protocol (MCP) Server**. By enabling `mcpMode`, the Actor transforms into a live Server-Sent Events (SSE) server that exposes powerful tools like `search_reddit` directly to AI Agents on your network.

***

### 🛠️ Detailed Input Configuration

The Actor allows extremely granular control over the crawling behavior:

| Field | Type | Description |
|---|---|---|
| **startUrls** | Array | List of specific URLs to start the scrape from. |
| **subredditUrls** | Array | List of subreddits to deeply extract. |
| **userUrls** | Array | Specific Reddit usernames or profile URLs to scrape. |
| **searchTerms** | Array | Specific keywords to search across the entire Reddit network. |
| **sortMode** | Dropdown | Allows you to target `hot`, `new`, `top_all`, etc. Select `all_sorts` to bypass the 1,000 item limit. |
| **maxPostsCount** | Number | Total maximum number of posts to pull. Set to `0` for infinite scraping. |
| **maxCommentsCount** | Number | Maximum total comments to scrape. |
| **crawlCommentsPerPost**| Boolean | If true, fetches deeply nested comment threads for every scraped post. |
| **enableAiFeatures** | Boolean | Toggle native LLM sentiment analysis and TL;DR summarization. |
| **openaiApiKey** | String | Your OpenAI secret key (Required if AI features enabled). |
| **downloadMedia** | Boolean | Save raw media buffers to Key-Value Store. |
| **webhookUrl** | String | POST every scraped post instantly to this endpoint (Slack/Discord/API). |
| **redditSessionCookie** | String | *(Secure/Hidden)* Inject your personal `reddit_session` to bypass NSFW filters. |
| **incrementalMode** | Boolean | Ideal for Apify scheduling; skips data scraped in the last run. |
| **startDate / endDate** | String | Time-travel filters. E.g. `2024-01-01` to only grab posts from 2024 onward. |
| **exportMarkdown** | Boolean | Generates a clean RAG-ready `.md` file in the Apify Key-Value Store. |
| **mcpMode** | Boolean | Turns the scraper into a persistent SSE MCP Server. |

***

### 📊 Dataset Output Schema

The JSON output is rigorously structured and robust. The dataset is specially configured with an **Output Schema View** so that it displays a clean, readable table in the Apify Console.

Key extracted fields include:

- `dataType`: Classifies the row as `"post"` or `"comment"`.
- `id`: The unique Reddit ID.
- `title`: The post title (Null for comments).
- `body`: The self-text or comment content.
- `authorName`: The Reddit username.
- `subredditName`: The community it was posted in.
- `upVotes`: Total upvotes on the post/comment.
- `commentsCount`: Total number of comments attached to the post.
- `mediaUrls`: Direct links to high-res images and MP4 videos attached to the post.
- `downloadedMediaUrls`: Direct links to physically downloaded media on Apify KV store.
- `aiSummary`: If enabled, a 1-sentence OpenAI TL;DR.
- `sentiment`: If enabled, the AI-determined sentiment (Positive/Negative/Toxic).
- `createdAt`: ISO 8601 Timestamp.

### 💸 Pay-Per-Event (PPE)

This Actor utilizes Apify's revolutionary Pay-Per-Event pricing model. You only pay for the exact amount of data you successfully extract!

### 🚨 Critical Note on Proxies

Reddit has extremely aggressive bot-protection. If you run this Actor using standard **Datacenter Proxies** (the default), your scraper will likely be blocked by Cloudflare (yielding 0 results) because Cloudflare instantly flags datacenter IPs.

**To guarantee successful scraping:** You MUST run this Actor on the Apify platform using **Residential Proxies** or provide your own Residential proxy URLs. Residential IPs look like real human devices and allow the Hybrid Stealth Engine to easily bypass the blocks and scrape the data!

# Actor input Schema

## `startUrls` (type: `array`):

Specific Reddit URLs to scrape (posts, users, subreddits). E.g. https://www.reddit.com/r/technology/

## `searchTerms` (type: `array`):

Keywords to search across Reddit.

## `subredditUrls` (type: `array`):

Names or URLs of subreddits to pull all history from (e.g. r/technology or https://www.reddit.com/r/technology/).

## `maxPostsCount` (type: `integer`):

Maximum number of posts to scrape per input.

## `maxCommentsCount` (type: `integer`):

Maximum total comments to scrape per input.

## `crawlCommentsPerPost` (type: `boolean`):

If enabled, extracts full comment threads for every post found.

## `fastMode` (type: `boolean`):

Scrapes Reddit JSON endpoints directly instead of loading heavy HTML. Blazing fast.

## `proxy` (type: `object`):

Select proxies to be used.

## `sortMode` (type: `string`):

Sorting criteria for subreddit or user posts.

## `redditSessionCookie` (type: `string`):

Paste your 'reddit_session' cookie value for authenticated private/NSFW browsing.

## `incrementalMode` (type: `boolean`):

Only scrape posts published after the previous run timestamp.

## `startDate` (type: `string`):

Filter posts created on or after this ISO date (e.g. 2026-01-01).

## `endDate` (type: `string`):

Filter posts created on or before this ISO date (e.g. 2026-12-31).

## `exportMarkdown` (type: `boolean`):

Saves an aggregated markdown dossier of all extracted content to key-value store 'RAG_EXPORT'.

## `userUrls` (type: `array`):

List of user profiles (e.g. u/spez or https://www.reddit.com/user/spez).

## `enableAiFeatures` (type: `boolean`):

Enriches every post and comment with an AI-generated 1-sentence TL;DR and sentiment label.

## `openaiApiKey` (type: `string`):

Required if enableAiFeatures is true.

## `downloadMedia` (type: `boolean`):

Downloads embedded images and videos directly to Apify Key-Value Store.

## `webhookUrl` (type: `string`):

POSTs every extracted record live to this webhook URL.

## `mcpMode` (type: `boolean`):

Starts an MCP Server with SSE on /mcp for Cursor, Claude Desktop, and AI agents.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://crawlee.dev"
    }
  ],
  "searchTerms": [],
  "subredditUrls": [
    "https://www.reddit.com/r/technology/"
  ],
  "maxPostsCount": 10,
  "maxCommentsCount": 10,
  "crawlCommentsPerPost": false,
  "fastMode": true,
  "proxy": {
    "useApifyProxy": true
  },
  "sortMode": "hot",
  "incrementalMode": false,
  "exportMarkdown": false,
  "userUrls": [],
  "enableAiFeatures": false,
  "downloadMedia": false,
  "mcpMode": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

View the full structured JSON dataset of scraped posts and comments.

## `datasetCsv` (type: `string`):

Download the scraped data as a spreadsheet.

## `ragExport` (type: `string`):

If exportMarkdown was enabled, view the stitched conversation tree here.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("litezero/reddit-mcp-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("litezero/reddit-mcp-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call litezero/reddit-mcp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,litezero/reddit-mcp-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/EOukZ09j0ssrt1A9b/builds/Q3doZ8cWkzbwrol6T/openapi.json