reddit-mcp

mcp-reddit

A full-featured Model Context Protocol (MCP) server for Reddit. Browse, search, post, comment, vote, message, and monitor keywords — all from your AI assistant.

Features

28 tools across 7 categories:

Category	Tools
Browse & Search	fetch_reddit_hot_threads, fetch_subreddit_posts, fetch_subreddit_info, fetch_reddit_post_content, search_reddit, fetch_front_page
User & Profile	fetch_user_profile, fetch_user_posts, fetch_user_comments, fetch_my_profile
Post	create_text_post, create_link_post, edit_post, delete_post, fetch_post_flair_choices
Comment	reply_to_post, reply_to_comment, edit_comment, delete_comment
Vote	vote (upvote, downvote, unvote on posts and comments)
Save	save_item, unsave_item
Message	send_message, fetch_inbox, fetch_unread_messages
Monitor	monitor_keywords (multi-keyword, multi-subreddit, deduplication, scoring)

Prerequisites

1. Python 3.11+
2. uv (recommended) or pip
3. Reddit API credentials — create an app at reddit.com/prefs/apps

Setup

1. Get Reddit API Credentials

1. Go to reddit.com/prefs/apps
2. Click "create another app..."
3. Fill in:
   • name: anything (e.g. mcp-reddit)
   • type: select web app
   • redirect uri: http://localhost:8080
4. Note your client ID (under the app name) and client secret

2. Get a Refresh Token

# Clone the repo
git clone https://github.com/raiansar/mcp-reddit.git
cd mcp-reddit

# Copy the example env and fill in your client ID and secret
cp .env.example .env
# Edit .env with your REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET

# Run the token generator
python get_token.py

This opens your browser for Reddit OAuth authorization. After approving, paste the redirect URL back into the terminal. The script saves your refresh token to .env.

3. Set Environment Variables

You need three environment variables:

REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_REFRESH_TOKEN=your_refresh_token

You can either put them in a .env file in the project root, or pass them directly in the MCP config (shown below).

Installation

Claude Code (CLI)

claude mcp add reddit -- uv run --directory /path/to/mcp-reddit mcp-reddit

Or with environment variables inline:

claude mcp add reddit \
  -e REDDIT_CLIENT_ID=your_client_id \
  -e REDDIT_CLIENT_SECRET=your_client_secret \
  -e REDDIT_REFRESH_TOKEN=your_refresh_token \
  -- uv run --directory /path/to/mcp-reddit mcp-reddit

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "reddit": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-reddit", "mcp-reddit"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Claude Cowork (settings.json)

Add to your project's .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "reddit": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-reddit", "mcp-reddit"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Install from PyPI (coming soon)

# Once published:
uvx mcp-reddit

Docker

docker build -t mcp-reddit .
docker run -e REDDIT_CLIENT_ID=... -e REDDIT_CLIENT_SECRET=... -e REDDIT_REFRESH_TOKEN=... mcp-reddit

Tool Reference

Browse & Search

Tool	Description
fetch_reddit_hot_threads(subreddit, limit)	Get hot posts from a subreddit
fetch_subreddit_posts(subreddit, sort, time_filter, limit)	Get posts with sort control (hot/new/top/rising/controversial)
fetch_subreddit_info(subreddit)	Get subreddit metadata (description, rules, subscribers)
fetch_reddit_post_content(post_id, comment_limit, comment_depth)	Get full post content with nested comment tree
search_reddit(query, subreddit, sort, time_filter, limit)	Search across Reddit or within a subreddit
fetch_front_page(sort, time_filter, limit)	Get front page posts (personalized when authenticated)

User & Profile

Tool	Description
fetch_user_profile(username)	Get a user's public profile (karma, cake day)
fetch_user_posts(username, sort, limit)	Get a user's submitted posts
fetch_user_comments(username, sort, limit)	Get a user's comments
fetch_my_profile()	Get your own profile info

Post (Write)

Tool	Description
create_text_post(subreddit, title, body, ...)	Submit a text/self post
create_link_post(subreddit, title, url, ...)	Submit a link post
edit_post(post_id, new_body)	Edit your own text post
delete_post(post_id)	Delete your own post
fetch_post_flair_choices(subreddit)	List available flair options for a subreddit

Comment (Write)

Tool	Description
reply_to_post(post_id, body)	Add a top-level comment
reply_to_comment(comment_id, body)	Reply to an existing comment
edit_comment(comment_id, new_body)	Edit your own comment
delete_comment(comment_id)	Delete your own comment

Vote & Save

Tool	Description
vote(target_id, direction, target_type)	Upvote (1), downvote (-1), or unvote (0)
save_item(target_id, target_type)	Save a post or comment
unsave_item(target_id, target_type)	Unsave a post or comment

Messaging

Tool	Description
send_message(to, subject, body)	Send a private message
fetch_inbox(limit)	Read inbox messages
fetch_unread_messages(limit)	Read unread messages only

Keyword Monitoring

Tool	Description
monitor_keywords(keywords, subreddits, since_minutes, limit_per_search, only_new)	Monitor multiple keywords across multiple subreddits with scoring, deduplication, and seen-post tracking

Examples

> What's hot on r/programming?
→ Uses fetch_reddit_hot_threads("programming")

> Search for "rust async" discussions from the past week
→ Uses search_reddit("rust async", sort="relevance", time_filter="week")

> Post a question to r/learnpython
→ Uses create_text_post("learnpython", "How do I...", "I'm trying to...")

> Monitor mentions of "claude" and "mcp" in r/LocalLLaMA and r/artificial
→ Uses monitor_keywords(["claude", "mcp"], ["LocalLLaMA", "artificial"])

License

MIT