Reddit MCP Buddy
Reddit Browser for Claude Desktop and AI Assistants
A Model Context Protocol (MCP) server that enables Claude Desktop and other AI assistants to browse Reddit, search posts, and analyze user activity. Clean, fast, and actually works - no API keys required.
🎬 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?
- 🚀 Zero setup - Works instantly, no Reddit API registration needed
- ⚡ Up to 10x more requests - Three-tier authentication system (10/60/100 requests per minute)
- 🎯 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
- ✅ Proven rate limits - Thoroughly tested authentication tiers with verification tools
Quick Start (30 seconds)
For Claude Desktop - Desktop Extension (Easiest!)
- Download: reddit-mcp-buddy.mcpb
- Install: Open the downloaded file
- 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
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
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.
Authentication (Optional)
Want more requests? Add Reddit credentials to your Claude Desktop config:
Setup Steps
- Go to https://www.reddit.com/prefs/apps
- Click "Create App" or "Create Another App"
- Fill out the form:
- Name: Any name (e.g., "reddit-mcp-buddy")
- App type: Select "script" (CRITICAL for 100 rpm!)
- Description: Optional
- About URL: Leave blank
- Redirect URI:
http://localhost:8080 (required but unused)
- Click "Create app"
- Find your credentials:
- Client ID: The string under "personal use script"
- Client Secret: The secret string
- 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"
}
}
}
}
Three-Tier Authentication System
Reddit MCP Buddy supports three authentication levels, each with different rate limits:
| Mode | Rate Limit | Required Credentials | Best For |
|---|
| Anonymous | 10 req/min | None | Testing, light usage |
| App-Only | 60 req/min | Client ID + Secret | Regular browsing |
| Authenticated | 100 req/min | All 4 credentials | Heavy usage, automation |
How It Works:
- Anonymous Mode: Default mode, no setup required, uses public Reddit API
- App-Only Mode: Uses OAuth2 client credentials grant (works with both script and web apps)
- Authenticated Mode: Uses OAuth2 password grant (requires script app type)
Important Notes:
- Script apps support BOTH app-only (60 rpm) and authenticated (100 rpm) modes
- Web apps only support app-only mode (60 rpm maximum)
- For 100 requests/minute, you MUST use a script app with username + password
Privacy & Data Handling
Reddit MCP Buddy is designed with privacy and transparency in mind. Here's how your data is handled:
Data Collection
- Reddit API Data: The server fetches public Reddit content (posts, comments, user profiles) through Reddit's official API
- No Tracking: We don't collect, store, or transmit any analytics, telemetry, or usage data
- No Third Parties: All data flows directly between your machine, Reddit's API, and your AI assistant
Local Storage
- Authentication Credentials (optional):
- Stored locally in
~/.reddit-mcp-buddy/auth.json when using --auth CLI setup
- Passwords are never written to disk - only used in-memory for OAuth token exchange
- Environment variables (recommended for Claude Desktop) are never persisted by this server
- Cache Data:
- Reddit API responses are temporarily cached in memory to improve performance
- Cache size limited to 50MB maximum
- All cache data is cleared when the server stops
- Can be disabled with
REDDIT_BUDDY_NO_CACHE=true
Data Transmission
- Reddit API Only: Your credentials are only sent to Reddit's official OAuth endpoints (
https://oauth.reddit.com and https://www.reddit.com)
- No External Services: No data is sent to any other external services, analytics platforms, or third parties
- Local Processing: All data processing happens locally on your machine
Security Notes
- Read-Only Operations: All tools are read-only - the server never posts, comments, or modifies any Reddit content
- Credential Safety:
- OAuth tokens are stored in memory and refreshed automatically
- Client secrets are treated as sensitive and never logged
- Use environment variables in Claude Desktop config for maximum security
- Open Source: Full source code is available at https://github.com/karanb192/reddit-mcp-buddy for security auditing
GDPR & Privacy Compliance
- No Personal Data Collection: We don't collect or process any personal data beyond what's necessary to authenticate with Reddit's API
- User Control: You control all credentials and can delete
~/.reddit-mcp-buddy/auth.json at any time
- Right to Erasure: Simply delete the auth file or uninstall the server to remove all local data
Questions or Concerns?
If you have any privacy questions or concerns, please open an issue on GitHub.
Testing & Development
Testing Your Rate Limits
Reddit MCP Buddy includes comprehensive testing tools to verify your authentication is working correctly:
git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
npm install
npm run test:rate-limit
npm run test:rate-limit:anon
npm run test:rate-limit:app
npm run test:rate-limit:auth
The rate limit tester will:
- Start a local server instance
- Make rapid API requests to test rate limits
- Display a real-time progress bar
- Confirm which authentication tier you're using
- Show exactly when rate limiting kicks in
Interactive Authentication Setup (for local testing only)
For local development and testing, you can set up authentication interactively:
npx -y reddit-mcp-buddy --auth
This will prompt you for Reddit app credentials and save them locally. Note: This does NOT work with Claude Desktop - use environment variables in your Claude config instead.
Testing with HTTP Mode
To test the server directly in your terminal:
npx -y reddit-mcp-buddy --http
REDDIT_BUDDY_PORT=8080 npx -y reddit-mcp-buddy --http
Note: The server runs in stdio mode by default (for Claude Desktop). Use --http flag for testing with Postman MCP or direct API calls.
Global Install
npm install -g reddit-mcp-buddy
reddit-buddy --http
From Source
git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
npm install
npm run build
npm link
Using Docker
docker run -it karanb192/reddit-mcp-buddy
Claude Desktop Extension
For one-click installation in Claude Desktop, download the pre-built extension:
📦 Download reddit-mcp-buddy.mcpb
Installation: Simply open the downloaded .mcpb file - Claude Desktop will automatically install the extension and the Reddit tools will be immediately available.
Build from Source (Optional)
If you prefer to build the extension yourself:
git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
./scripts/build-mcpb.sh
Note: The Desktop Extension format is currently in preview (September 2025). Most users should use the standard npm installation method shown in Quick Start.
| Feature | Reddit MCP Buddy | Other MCP Tools |
|---|
| Zero Setup | ✅ Works instantly | ❌ Requires API keys |
| Max Rate Limit | ✅ 100 req/min proven | ❓ Unverified claims |
| Language | TypeScript/Node.js | Python (most) |
| Tools Count | 5 (focused) | 8-10 (redundant) |
| Fake Metrics | ✅ Real data only | ❌ "Sentiment scores" |
| Search | ✅ Full search | Limited or none |
| Caching | ✅ Smart caching | Usually none |
| LLM Optimized | ✅ Clear params | Confusing options |
| Rate Limit Testing | ✅ Built-in tools | ❌ No verification |
Rate Limits
| Mode | Requests/Minute | Cache TTL | Setup Required |
|---|
| Anonymous | 10 | 15 min | None |
| App-only | 60 | 5 min | Client ID + Secret |
| Authenticated | 100 | 5 min | All credentials |
Why Reddit MCP Buddy?
What others do wrong:
- ❌ Fake metrics - "sentiment scores" that are just keyword counting
- ❌ Complex setup - Requiring API keys just to start
- ❌ Bloated responses - Returning 100+ fields of Reddit's raw API
- ❌ Poor LLM integration - Confusing parameters and unclear descriptions
What we do right:
- ✅ Real data only - If it's not from Reddit's API, we don't make it up
- ✅ Clean responses - Only the fields that matter
- ✅ Clear parameters - LLMs understand exactly what to send
- ✅ Fast & cached - Responses are instant when possible
Examples
Your AI can now answer:
"What are the top posts about GPT-4 today?"
→ search_reddit with query="GPT-4", time="day", sort="top"
"Show me what's trending in technology"
→ browse_subreddit with subreddit="technology", sort="hot"
"What do people think about this article?"
→ search_reddit with the article URL to find discussions
"Analyze the user DeepFuckingValue"
→ user_analysis with username="DeepFuckingValue"
"Get the comments from this Reddit post"
→ get_post_details with url="https://reddit.com/r/..."
"What's trending across all of Reddit?"
→ browse_subreddit with subreddit="all", sort="hot"
Troubleshooting
Common Issues
"Can't achieve 100 requests/minute"
- Ensure your app type is "script" not "web" or "installed"
- Script apps created by one account can only authenticate as that same account
- Run
npm run test:rate-limit:auth to verify (requires cloning the repo)
- If still failing, create a new script app while logged into the authenticating account
"Command not found" error
node --version
npm --version
$(npm bin -g)/reddit-mcp-buddy
Rate limit errors
- Without auth: Limited to 10 requests/minute
- With app credentials only: 60 requests/minute
- With full authentication: 100 requests/minute
- Solution: Add Reddit credentials (see Authentication)
"Subreddit not found"
- Check spelling (case-insensitive)
- Some subreddits may be private or quarantined
- Try "all" or "popular" instead
Connection issues
Environment Variables
Authentication Variables
| Variable | Description | Required | Rate Limit |
|---|
REDDIT_CLIENT_ID | Reddit app client ID | No | 60 req/min (with secret) |
REDDIT_CLIENT_SECRET | Reddit app secret | No | 60 req/min (with ID) |
REDDIT_USERNAME | Reddit account username | No | 100 req/min (with all 4) |
REDDIT_PASSWORD | Reddit account password | No | 100 req/min (with all 4) |
REDDIT_USER_AGENT | User agent string | No | - |
Server Configuration
| Variable | Description | Default |
|---|
REDDIT_BUDDY_HTTP | Run as HTTP server instead of stdio | false |
REDDIT_BUDDY_PORT | HTTP server port (when HTTP=true) | 3000 |
REDDIT_BUDDY_NO_CACHE | Disable caching (always fetch fresh) | false |
Technical Details
Smart Caching System
Reddit MCP Buddy includes intelligent caching to improve performance and reduce API calls:
- Memory Safe: Hard limit of 50MB - won't affect your system performance
- Adaptive TTLs: Hot posts (5min), New posts (2min), Top posts (30min)
- LRU Eviction: Automatically removes least-used data when approaching limits
- Hit Tracking: Optimizes cache based on actual usage patterns
This means faster responses and staying well within Reddit's rate limits, all while using minimal system resources.
Development
npm install
npm run dev
npm run build
npm test
npm run test:integration
npm run test:all
npm run test:rate-limit
npm run test:rate-limit:anon
npm run test:rate-limit:app
npm run test:rate-limit:auth
npm run lint
npm run typecheck
Requirements
- Node.js >= 18.0.0
- npm or yarn
- TypeScript 5.5+
Contributing
PRs welcome! See CONTRIBUTING.md for guidelines.
We keep things simple:
- No fake analytics
- Clean, typed code
- Clear documentation
- Fast responses
Support
Official MCP Resources
Where to Find This Server
View All Versions via API
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | jq
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | \
jq '.servers[] | {version, id: ._meta."io.modelcontextprotocol.registry/official".id}'
License
MIT - Use it however you want!
Made with ❤️ for the MCP community. No venture capital, no tracking, just a good MCP server.