io.github.jordanburke/reddit-mcp-server

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	:white_check_mark:	:x:
Reply to Posts/Comments	:white_check_mark:	:x:
Edit Posts/Comments	:white_check_mark:	:x:
Delete Posts/Comments	:white_check_mark:	:x:
Spam Protection (Safe Mode)	:white_check_mark:	:x:
Bot Disclosure Footer	:white_check_mark:	:x:
Policy Compliance Built-in	:white_check_mark:	:x:
Browse Subreddits	:white_check_mark:	:white_check_mark:
Search Reddit	:white_check_mark:	:white_check_mark:
User Analysis	:white_check_mark:	:white_check_mark:
Post Comments	:white_check_mark:	:white_check_mark:
OAuth Auth (60-100 rpm)	:white_check_mark:	:white_check_mark:
RSS Fallback (zero-setup)	:white_check_mark:	:x:

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)

Add to your MCP config (Claude Desktop, Cursor, etc.) with Reddit OAuth credentials:

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["reddit-mcp-server"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Option 3: Claude Code

REDDIT_CLIENT_ID=your_client_id REDDIT_CLIENT_SECRET=your_client_secret \
  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
save_content	Save a post or comment to your account
unsave_content	Remove a post or comment from your saved items
delete_post	Permanently delete your own post
delete_comment	Permanently delete your own comment

Configuration

Environment Variables

Variable	Required	Default	Description
REDDIT_CLIENT_ID	Yes	-	Reddit app client ID (OAuth required since mid-2026)
REDDIT_CLIENT_SECRET	Yes	-	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 deprecated)
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)

Reddit closed self-service app creation in November 2025. See Authentication for how to get credentials.

Full MCP Config Example

{
  "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:

export REDDIT_SAFE_MODE=off
npx reddit-mcp-server

What Safe Mode Does

1. Rate Limiting: Enforces minimum delays between write operations
2. Duplicate Detection: Blocks identical content from being posted twice
3. Cross-Subreddit Detection: Prevents posting the same content to multiple subreddits (per Reddit policy)
4. 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:

export REDDIT_BOT_DISCLOSURE=auto
npx reddit-mcp-server

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

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

Customize the footer with REDDIT_BOT_FOOTER:

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

Authentication

⚠️ Reddit API Changes (2026)

Anonymous mode no longer works. As of mid-2026, Reddit blocks all unauthenticated API requests with HTTP 403. OAuth credentials are now required for any API access.

Additionally, Reddit closed self-service OAuth app creation in November 2025. New developers must request access through Reddit's Developer Support. Existing OAuth credentials (obtained before November 2025) continue to work.

Getting Credentials

If you already have a Reddit app (created at /prefs/apps before November 2025): use your existing client ID and secret — they still work at 60-100 req/min.

If you need new credentials: submit a request through Reddit's Developer Support describing your use case. Approval is required and may take time.

Mode Comparison

Mode	Rate Limit	Setup Required	Tools Available	Best For
auto (default)	60-100 req/min	OAuth credentials	All tools	Most users
authenticated	60-100 req/min	OAuth credentials	All tools	Explicit mode
auto (no creds)	~1 req/min	None	browse_subreddit, get_top_posts only (RSS)	Quick testing
anonymous	~1 req/min	None	browse_subreddit, get_top_posts only (RSS)	Legacy alias

RSS Fallback Mode

When no OAuth credentials are provided, the server automatically falls back to Reddit's public RSS feeds. This gives you zero-setup access to browse subreddits and get top posts.

What works: browse_subreddit and get_top_posts — returns up to 25 posts per request.

What's missing compared to OAuth:

• No engagement metrics (score, comments, upvote ratio are all 0)
• No pagination (single page of ~25 results)
• No search, user info, comments, or write operations
• Lower rate limit (~1 req/min vs 60-100 with OAuth)

RSS results include a disclaimer noting the data source. All other tools return a clear error directing you to set up OAuth credentials.

Read-Only Access (OAuth)

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

Write Operations (OAuth + User Credentials)

To create posts, reply, edit, or delete content, add your Reddit username and password:

{
  "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"
  }
}

Development

Commands

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

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:

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

With OAuth Protection

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:

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

Docker

Quick Start

# 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

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

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