reddit-mcp

A read-only MCP server built for Claude that connects to the Reddit Data API (oauth.reddit.com). Search posts, browse subreddits, read comments, view user profiles, and check trending content — all through the Model Context Protocol.

Quick Install (Claude Code)

npx -y @hamzashahbaz/reddit-mcp

Or add it to Claude Code with environment variables:

claude mcp add reddit -e REDDIT_CLIENT_ID=your_id -e REDDIT_CLIENT_SECRET=your_secret -e REDDIT_USERNAME=your_username -e REDDIT_PASSWORD=your_password -- npx -y @hamzashahbaz/reddit-mcp

Features

• Search Reddit -- query posts across all of Reddit or within a specific subreddit

• Browse subreddits -- get posts sorted by hot, new, top, or rising

• Read comments -- fetch a post's details and top-level comments

• User profiles -- view profile info and recent activity (posts, comments, or both)

• Trending posts -- see what's popular on r/popular

Prerequisites

• Node.js 18+

• A Reddit account

• A Reddit "script" application (free) -- see Setup

Setup

1. Request Reddit API access

Reddit requires API access approval before you can create apps.

1. Go to Reddit Help — Submit a request

2. Select API Access Request

3. Fill in the form:

   • Benefit/purpose: Read-only content browsing tool that helps users discover and read Reddit content through AI assistants — no posting, commenting, or voting.

   • Detailed description: reddit-mcp is an open-source MCP (Model Context Protocol) server that provides read-only access to Reddit's public content. It allows AI assistants to search posts, browse subreddits, read comments, and view user profiles. All operations are read-only GET requests. Source code: https://github.com/hamzashahbaz/reddit-mcp

   • Devvit question: This tool is an external read-only client that integrates Reddit content into AI workflows — a use case outside Devvit's scope.

   • Source code link: https://github.com/hamzashahbaz/reddit-mcp

   • Subreddits: General-purpose — works with any public subreddit

4. Submit and wait for approval (typically a few days)

2. Create a Reddit script app

Once approved:

1. Go to reddit.com/prefs/apps

2. Click "create another app..."

3. Fill in:

   • name: anything (e.g., mcp-reader)

   • type: select script

   • redirect uri: http://localhost:8080 (not used, but required)

4. Note your client ID (under the app name) and client secret

3. Clone and build

git clone https://github.com/hamzashahbaz/reddit-mcp.git
cd reddit-mcp
npm install
npm run build

Configuration

Add to your .mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "reddit": {
      "command": "node",
      "args": ["/path/to/reddit-mcp/dist/server.js"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_reddit_username",
        "REDDIT_PASSWORD": "your_reddit_password"
      }
    }
  }
}

Replace /path/to/reddit-mcp with the actual path to your cloned directory.

Tools

Parameter details

• sort (search): relevance, hot, top, new

• sort (subreddit): hot, new, top, rising

• sort (comments): best, top, new, controversial

• time_filter: hour, day, week, month, year, all

• content_type: overview, posts, comments

• limit: 1-25 for most tools, 1-50 for comments

How it works

• Uses the Reddit Data API (REST) at https://oauth.reddit.com

• Authenticates via OAuth 2.0 password grant (script app)

• All operations are read-only GET requests

• Tokens cached in memory, auto-refreshed before expiry

• Respects Reddit rate limits (100 req/min authenticated)

• Built for Claude Code and Claude Desktop via the Model Context Protocol (MCP)

License

MIT