Reddit MCP Buddy

Reddit MCP Buddy

Reddit Browser for Claude Desktop and AI Assistants

A Model Context Protocol (MCP) server for browsing Reddit, searching posts, and analyzing user activity. Anonymous browsing uses Reddit's public RSS feeds when available. Search, comments, user analysis, and full metrics require approved Reddit API access. Version 1.2.0 adds optional posting and commenting with per-process caps and a client-dependent confirmation flow. See Posting.

🎬 See It In Action

*Claude checking Reddit's reaction to the Dune Part Three trailer and whether the AirPods Max 2 are worth $549*

*Claude analyzing real-time sentiment about H-1B visa changes across r/cscareerquestions and r/india*

Table of Contents

• What makes Reddit MCP Buddy different?
• Quick Start
• What can it do?
• Available Tools
• Authentication
• Posting (v1.2.0)
• Installation Options
• Global Install
• From Source
• Using Docker
• Claude Desktop Extension
• Comparison with Other Tools
• Troubleshooting
• Development
• Support
• Related Resources

What makes Reddit MCP Buddy different?

• 🚀 Anonymous browsing - Browse subreddits through public RSS feeds when available; other live-data tools need approved API access
• ✍️ Opt-in posting (v1.2.0) - Create posts and comments with a client-dependent confirmation flow, per-process caps, and duplicate suppression
• ⚡ Local rate limits - Configured caps of 10/60/100 requests per minute; Reddit applies its own limits
• 🎯 Clean data - No fake "sentiment analysis" or made-up metrics
• 🧠 LLM-optimized - Built specifically for AI assistants like Claude
• 📦 TypeScript - Fully typed, reliable, and maintainable
• ✅ Rate-limit testing - Verification tools for the server's local authentication tiers

Quick Start (30 seconds)

For Claude Desktop - Desktop Extension (Easiest!)

1. Download: reddit-mcp-buddy.mcpb
2. Install: Open the downloaded file
3. Done! Reddit tools are now available in Claude

For Claude Desktop - NPM Method (Alternative)

Add this to your claude_desktop_config.json:

{

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

For Claude Code

Run this command to add the MCP server (user scope):

claude mcp add --transport stdio reddit-mcp-buddy -s user -- npx -y reddit-mcp-buddy

For Other MCP Clients

Use the NPM method: npx -y reddit-mcp-buddy

What can it do?

Ask your AI assistant to:

• 📊 "What's trending on Reddit?" - Browse hot posts from r/all
• 🔍 "Search for discussions about AI" - Search across all subreddits
• 💬 "Get comments from this Reddit post" - Fetch post with full comment threads
• 👤 "Analyze user spez" - Get user history, karma, and activity
• 📚 "Explain Reddit karma" - Understand Reddit terminology
• ✍️ "Post this to r/test" - Draft, check the sub's rules, and submit after you confirm (opt-in, see Posting)

Available Tools

browse_subreddit

Browse posts from any subreddit with sorting options.

- Subreddit:

• "all" - entire Reddit frontpage
• "popular" - trending across Reddit
• Any specific subreddit (e.g., "technology", "programming", "science")
• Sort by: hot, new, top, rising, controversial
• Time range: hour, day, week, month, year, all (for top/controversial sort)
• Include subreddit info: Optional flag for subreddit metadata (requires credentials)

No credentials? Results are served from Reddit's public RSS feed (data_source: "rss"): score, num_comments, upvote_ratio, and nsfw come back null, and the include_nsfw filter can't be applied. Add credentials (Authentication) for full data via the API.

search_reddit

Search across Reddit or specific subreddits.

- Query: Your search terms

• Filter by: subreddit, author, time, flair
• Sort by: relevance, hot, top, new, comments

get_post_details

Get a post with all its comments.

- Input:

• Reddit URL (supports multiple formats), OR
• Post ID alone (will auto-detect subreddit, 2 API calls), OR
• Post ID + subreddit (most efficient, 1 API call)
• Supported URL formats:
• reddit.com, www.reddit.com
• old.reddit.com, new.reddit.com
• np.reddit.com (No Participation links)
• m.reddit.com (mobile links)
• redd.it short URLs
• URLs with query params (?utm_source=...) or fragments (#comment)
• Options: comment sorting, depth, link extraction

user_analysis

Analyze a Reddit user's profile.

- Username: Any Reddit user

• Returns: karma, posts, comments, active subreddits

reddit_explain

Get explanations of Reddit terms.

- Terms: karma, cake day, AMA, ELI5, etc.

Write tools (opt-in)

create_post, add_comment, and subreddit_rules only appear when you enable posting; read-only installs see exactly the five tools above. Details in Posting (v1.2.0).

Authentication (Optional)

Search, post details, user analysis, and full metrics require Reddit API credentials for an approved app and use case.

Reddit API approval

Reddit's Responsible Builder Policy requires explicit approval before using its API. Creating an app is not a self-service guarantee of access. Reddit directs developers to Devvit first; for use cases Devvit does not support, use Reddit's API access request form.

If you already have approved access, use your app's credentials below. This project cannot grant approval or guarantee an approval timeline, and it does not provide shared API keys or a third-party OAuth service.

Without credentials, browse_subreddit can use public RSS feeds and reddit_explain works offline. RSS can be blocked or throttled and does not provide engagement metrics or NSFW flags. It does not enable search, post details, or user analysis, and it does not grant API approval.

Setup Steps

1. Obtain Reddit API approval for your app and use case using the links above.
2. Open https://www.reddit.com/prefs/apps and select your approved app. If Reddit instructs you to create an app, follow its instructions.
3. Fill out the form:

• Name: For example, "mcp-buddy". Reddit rejects client names containing "reddit".
• App type: Use "script" for password-grant authentication or "web app" for OAuth consent with a refresh token. App-only mode supports both.
• Description: Optional
• About URL: Leave blank
• Redirect URI: Your registered OAuth callback, such as http://localhost:8080. It is unused by password-grant authentication.

1. Complete app registration as directed by Reddit. If creation is unavailable, follow up through Reddit's access request process.
2. Find your credentials:

• Client ID: The string beneath the app's name and type
• Client Secret: The secret string

1. Update your Claude Desktop config:

{

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

Web apps with OAuth consent

An approved web app can authenticate a user without their Reddit password. --oauth runs Reddit's authorization-code flow once and prints a refresh token.

1. Register the redirect URI. On Reddit app preferences, the web app's redirect URI must be a loopback address with a port, such as http://localhost:8080.
2. Run the consent command on the machine where your browser is signed in to Reddit:

   npx -y reddit-mcp-buddy --oauth

It prompts for the web app's client ID and secret, or reads REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET from the environment. It requests identity, read, and history, which the read-only tools need. Add --write to also request submit and flair for posting. Pass --redirect-uri http://localhost: if you registered a different port.

1. Open the printed link and click Allow. Reddit redirects back to a temporary local server that only listens on your machine. It checks the random state value, exchanges the one-time code, and confirms the account with /api/v1/me. It waits up to 5 minutes and never posts.
2. Copy the token into your config. It prints REDDIT_REFRESH_TOKEN=.... To keep it off the screen, add --out ~/reddit-token.env, a path outside any repository. If that file already exists, the command stops before asking for consent. If writing fails after consent, it prints the token instead. On macOS and Linux the file is readable only by you.

Set these variables in the server's environment:

{

"REDDIT_CLIENT_ID": "your_client_id", "REDDIT_CLIENT_SECRET": "your_client_secret", "REDDIT_REFRESH_TOKEN": "your_refresh_token" }

Leave REDDIT_PASSWORD unset when using a refresh token. Setting both is rejected at startup. The server exchanges the refresh token for access tokens as needed and does not write environment credentials to auth.json. Refresh tokens loaded from that file are not used; configure this mode through the environment.

Treat a refresh token like a password. Keep it outside version control and revoke access in Reddit app preferences when it is no longer needed. OAuth consent does not grant Reddit API approval or extend the approved use case.

Three-Tier Authentication System

Reddit MCP Buddy enforces these local caps. They are not Reddit API quotas or guaranteed throughput:

*\*Server-side cap. Anonymous requests are served from Reddit's logged-out RSS feed, which applies its own stricter per-IP throttle (often one uncached request per 25-60 seconds). The 15-minut