io.github.jordanburke/reddit-mcp-server

Official

by jordanburke · TypeScript

Reddit MCP server with full read/write - posts, comments, search, and content creation.

Full Reddit access via MCP for reading, posting, commenting, and searching.

Reddit MCP Server

A Model Context Protocol (MCP) server for interacting with Reddit - fetch posts, comments, user info, and create content.

Features at a Glance

Feature	reddit-mcp-server	Other Reddit MCPs
Create Posts	✅	❌
Reply to Posts/Comments	✅	❌
Edit Posts/Comments	✅	❌
Delete Posts/Comments	✅	❌
Spam Protection (Safe Mode)	✅	❌
Bot Disclosure Footer	✅	❌
Policy Compliance Built-in	✅	❌
Browse Subreddits	✅	✅
Search Reddit	✅	✅
User Analysis	✅	✅
Post Comments	✅	✅
Zero-Setup Anonymous Mode	✅	✅
Three-Tier Auth (10/60/100 rpm)	✅	✅

Quick Start

Option 1: Claude Desktop Extension (Easiest)

Download and open the extension file - Claude Desktop will install it automatically:

Download reddit-mcp-server.mcpb

Option 2: NPX (No install required)

bash

npx reddit-mcp-server

Or add to your MCP config (Claude Desktop, Cursor, etc.):

json

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["reddit-mcp-server"]
    }
  }
}

Option 3: Claude Code

bash

claude mcp add --transport stdio reddit -- npx reddit-mcp-server

Features

Read-only Tools

Tool	Description
`get_reddit_post`	Get a specific Reddit post with engagement analysis
`get_top_posts`	Get top posts from a subreddit or home feed
`browse_subreddit`	Browse a subreddit/home feed by sort (hot, new, top, rising, controversial)
`get_user_info`	Get detailed information about a Reddit user
`get_user_posts`	Get posts submitted by a specific user
`get_user_comments`	Get comments made by a specific user
`get_subreddit_info`	Get subreddit details and statistics
`get_trending_subreddits`	Get currently trending subreddits
`get_post_comments`	Get comments from a specific post with threading
`search_reddit`	Search for posts across Reddit

Write Tools (Require User Credentials)

Tool	Description
`create_post`	Create a new post in a subreddit
`reply_to_post`	Post a reply to an existing post or comment
`edit_post`	Edit your own Reddit post (self-text only)
`edit_comment`	Edit your own Reddit comment
`delete_post`	Permanently delete your own post
`delete_comment`	Permanently delete your own comment

Configuration

Environment Variables

Variable	Required	Default	Description
`REDDIT_CLIENT_ID`	No*	-	Reddit app client ID
`REDDIT_CLIENT_SECRET`	No*	-	Reddit app client secret
`REDDIT_USERNAME`	No	-	Reddit username (for write operations)
`REDDIT_PASSWORD`	No	-	Reddit password (for write operations)
`REDDIT_USER_AGENT`	No	Auto-generated	Custom User-Agent string
`REDDIT_AUTH_MODE`	No	`auto`	Authentication mode: `auto`, `authenticated`, `anonymous`
`REDDIT_SAFE_MODE`	No	`standard`	Write safeguards: `off`, `standard`, `strict`
`REDDIT_BOT_DISCLOSURE`	No	`off`	Bot disclosure footer: `auto`, `off`
`REDDIT_BOT_FOOTER`	No	Built-in	Custom bot footer text (when disclosure is `auto`)
`REDDIT_CACHE`	No	`on`	In-memory caching of read requests: `on`, `off`
`REDDIT_CACHE_MAX_MB`	No	`50`	Cache size cap in MB (LRU eviction beyond this)
`REDDIT_MAX_RETRIES`	No	`3`	Retries on HTTP 429 with Retry-After backoff (`0` to disable)

*Required only if using authenticated mode.

Full MCP Config Example

json

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["reddit-mcp-server"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "REDDIT_SAFE_MODE": "standard"
      }
    }
  }
}

Safe Mode (Spam Protection)

Protect your Reddit account from spam detection and bans with built-in safeguards. Enabled by default (standard mode) per Reddit's Responsible Builder Policy.

Why Use Safe Mode?

Reddit's spam detection can flag accounts for:

Rapid posting or commenting
Duplicate or similar content
Posting the same content across multiple subreddits
Non-standard User-Agent strings

Safe Mode helps prevent these issues automatically.

Mode Options

Mode	Write Delay	Duplicate Detection	Use Case
`off`	None	No	Explicit opt-out only
`standard`	2 seconds	Last 10 items + cross-sub	Default, recommended
`strict`	5 seconds	Last 20 items + cross-sub	For cautious automated posting

Disable Safe Mode

Safe mode is enabled by default. To explicitly disable:

bash

export REDDIT_SAFE_MODE=off
npx reddit-mcp-server

What Safe Mode Does

Rate Limiting: Enforces minimum delays between write operations
Duplicate Detection: Blocks identical content from being posted twice
Cross-Subreddit Detection: Prevents posting the same content to multiple subreddits (per Reddit policy)
Smart User-Agent: Auto-generates Reddit-compliant User-Agent format when username is provided

Bot Disclosure

Reddit's Responsible Builder Policy requires bots to disclose their automated nature. Enable automatic bot footers on all posted content:

bash

export REDDIT_BOT_DISCLOSURE=auto
npx reddit-mcp-server

When enabled, a footer is appended to all posts, replies, and edits:

code

---
🤖 I am a bot | Built with reddit-mcp-server

Customize the footer with REDDIT_BOT_FOOTER:

bash

export REDDIT_BOT_DISCLOSURE=auto
export REDDIT_BOT_FOOTER=$'\n\n---\n^(🤖 Custom bot footer text)'

Authentication Modes

Mode Comparison

Mode	Rate Limit	Setup Required	Best For
`anonymous`	~10 req/min	None	Quick testing, read-only
`auto` (default)	10-100 req/min	Optional	Flexible usage
`authenticated`	60-100 req/min	Required	Production use

Anonymous Mode (Zero Setup)

json

{
  "env": {
    "REDDIT_AUTH_MODE": "anonymous"
  }
}

Authenticated Mode (Higher Rate Limits)

Create a Reddit app at https://www.reddit.com/prefs/apps (select "script" type)
Copy the client ID and secret
Configure:

json

{
  "env": {
    "REDDIT_AUTH_MODE": "authenticated",
    "REDDIT_CLIENT_ID": "your_client_id",
    "REDDIT_CLIENT_SECRET": "your_client_secret"
  }
}

Write Operations

To create posts, reply, edit, or delete content, you need user credentials:

json

{
  "env": {
    "REDDIT_USERNAME": "your_username",
    "REDDIT_PASSWORD": "your_password",
    "REDDIT_SAFE_MODE": "standard"
  }
}

Development

Commands

bash

pnpm install        # Install dependencies
pnpm build          # Build TypeScript
pnpm dev            # Build and run MCP inspector
pnpm test           # Run tests
pnpm lint           # Lint code
pnpm format         # Format code

CLI Options

bash

npx reddit-mcp-server --version         # Show version
npx reddit-mcp-server --help            # Show help
npx reddit-mcp-server --generate-token  # Generate OAuth token for HTTP mode

HTTP Server Mode

For Docker deployments or web-based clients, use HTTP transport:

bash

TRANSPORT_TYPE=httpStream PORT=3000 node dist/index.js

With OAuth Protection

bash

export OAUTH_ENABLED=true
export OAUTH_TOKEN=$(npx reddit-mcp-server --generate-token | tail -1)
TRANSPORT_TYPE=httpStream node dist/index.js

Make authenticated requests:

bash

curl -H "Authorization: Bearer $OAUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"method":"tools/list","params":{}}' \
     http://localhost:3000/mcp

Docker

Quick Start

bash

# Pull and run
docker pull ghcr.io/jordanburke/reddit-mcp-server:latest

docker run -d \
  --name reddit-mcp \
  -p 3000:3000 \
  -e REDDIT_CLIENT_ID=your_client_id \
  -e REDDIT_CLIENT_SECRET=your_client_secret \
  -e REDDIT_SAFE_MODE=standard \
  ghcr.io/jordanburke/reddit-mcp-server:latest

Docker Compose

yaml

services:
  reddit-mcp:
    image: ghcr.io/jordanburke/reddit-mcp-server:latest
    ports:
      - "3000:3000"
    environment:
      - REDDIT_CLIENT_ID=${REDDIT_CLIENT_ID}
      - REDDIT_CLIENT_SECRET=${REDDIT_CLIENT_SECRET}
      - REDDIT_USERNAME=${REDDIT_USERNAME}
      - REDDIT_PASSWORD=${REDDIT_PASSWORD}
      - REDDIT_SAFE_MODE=standard
      - OAUTH_ENABLED=${OAUTH_ENABLED:-false}
      - OAUTH_TOKEN=${OAUTH_TOKEN}
    restart: unless-stopped

Build Locally

bash

docker build -t reddit-mcp-server .
docker run -d --name reddit-mcp -p 3000:3000 --env-file .env reddit-mcp-server

Reddit Responsible Builder Policy

This server is designed with Reddit's Responsible Builder Policy in mind:

Safe mode on by default — rate limiting and duplicate detection prevent spam
Cross-subreddit duplicate detection — blocks identical content across subreddits
Bot disclosure support — optional automated footer for transparency
No voting/karma manipulation — upvote/downvote tools are intentionally excluded
No private messaging — DM tools are intentionally excluded
Policy-aware AI instructions — MCP server instructions remind AI assistants of data usage restrictions

Credits

Fork of reddit-mcp-server by Alexandros Lekkas
Inspired by Python Reddit MCP Server by Arindam200

Install

Configuration

Environment variables

REDDIT_CLIENT_ID

Reddit app client ID (optional - enables higher rate limits)

REDDIT_CLIENT_SECRETsecret

Reddit app client secret

REDDIT_USERNAME

Reddit username (required for write operations)

REDDIT_PASSWORDsecret

Reddit password (required for write operations)

REDDIT_AUTH_MODE

Authentication mode: auto, authenticated, or anonymous

REDDIT_SAFE_MODE

Write safeguards: off, standard (default), or strict

REDDIT_BOT_DISCLOSURE

Bot disclosure footer: auto or off (default)

REDDIT_BOT_FOOTER

Custom bot footer text (used with REDDIT_BOT_DISCLOSURE=auto)

claude_desktop_config.json

{
  "mcpServers": {
    "reddit-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "reddit-mcp-server@1.5.1"
      ],
      "env": {
        "REDDIT_CLIENT_ID": "<YOUR_REDDIT_CLIENT_ID>",
        "REDDIT_CLIENT_SECRET": "<YOUR_REDDIT_CLIENT_SECRET>",
        "REDDIT_USERNAME": "<YOUR_REDDIT_USERNAME>",
        "REDDIT_PASSWORD": "<YOUR_REDDIT_PASSWORD>",
        "REDDIT_AUTH_MODE": "<YOUR_REDDIT_AUTH_MODE>",
        "REDDIT_SAFE_MODE": "<YOUR_REDDIT_SAFE_MODE>",
        "REDDIT_BOT_DISCLOSURE": "<YOUR_REDDIT_BOT_DISCLOSURE>",
        "REDDIT_BOT_FOOTER": "<YOUR_REDDIT_BOT_FOOTER>"
      }
    }
  }
}