Reddit Buddy MCP

# <img src="assets/reddit-mcp-buddy-icon-white-background.png" width="48" align="center"/> Reddit MCP Buddy ### Reddit Browser for Claude Desktop and AI Assistants A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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. [](https://registry.modelcontextprotocol.io/v0/servers/5677b351-373d-4137-bc58-28f1ba0d105d) [](https://www.npmjs.com/package/reddit-mcp-buddy) [](https://www.npmjs.com/package/reddit-mcp-buddy) [](https://github.com/karanb192/reddit-mcp-buddy/stargazers) [](https://opensource.org/licenses/MIT) ## 🎬 See It In Action  *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?](#what-makes-reddit-buddy-different) - [Quick Start](#quick-start-30-seconds) - [What can it do?](#what-can-it-do) - [Available Tools](#available-tools) - [Authentication](#authentication-optional) - [Installation Options](#installation-options) - [Global Install](#global-install) - [From Source](#from-source) - [Using Docker](#using-docker) - [Claude Desktop Extension](#claude-desktop-extension) - [Comparison with Other Tools](#comparison-with-other-tools) - [Troubleshooting](#troubleshooting) - [Development](#development) - [Support](#support) - [Related Resources](#-related-resources) ## 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!) 1. **Download**: [reddit-mcp-buddy.mcpb](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/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`: ```json { "mcpServers": { "reddit": { "command": "npx", "args": ["reddit-mcp-buddy"] } } } ``` ### For Other MCP Clients Use the NPM method: `npx 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 ## 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 ``` ### `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 (full URL including subreddit), OR - Post ID alone (will auto-detect subreddit, 2 API calls), OR - Post ID + subreddit (most efficient, 1 API call) - 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 1. **Go to** https://www.reddit.com/prefs/apps 2. **Click** "Create App" or "Create Another App" 3. **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) 4. **Click** "Create app" 5. **Find your credentials:** - **Client ID**: The string under "personal use script" - **Client Secret**: The secret string 6. **Update your Claude Desktop config:** ```json { "mcpServers": { "reddit": { "command": "npx", "args": ["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 ## Testing & Development ### Testing Your Rate Limits Reddit MCP Buddy includes comprehensive testing tools to verify your authentication is working correctly: ```bash # Clone the repository first git clone https://github.com/karanb192/reddit-mcp-buddy.git cd reddit-mcp-buddy npm install # Test with your current environment settings npm run test:rate-limit # Test specific authentication modes npm run test:rate-limit:anon # Test anonymous mode (10 rpm) npm run test:rate-limit:app # Test app-only mode (60 rpm) npm run test:rate-limit:auth # Test authenticated mode (100 rpm) ``` 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: ```bash npx 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: ```bash # Run in HTTP mode on port 3000 npx reddit-mcp-buddy --http # Or with custom port REDDIT_BUDDY_PORT=8080 npx 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 ```bash npm install -g reddit-mcp-buddy reddit-buddy --http # For testing ``` ### From Source ```bash git clone https://github.com/karanb192/reddit-mcp-buddy.git cd reddit-mcp-buddy npm install npm run build npm link ``` ### Using Docker ```bash 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](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/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: ```bash 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](#quick-start-30-seconds). ## Comparison with Other Tools | 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** ```bash # Ensure npm is installed node --version npm --version # Try with full npx path $(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](#authentication-optional)) **"Subreddit not found"** - Check spelling (case-insensitive) - Some subreddits may be private or quarantined - Try "all" or "popular" instead **Connection issues** - Reddit may be down (check https://www.redditstatus.com) - Firewall blocking requests - Try restarting the MCP server ### 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 ```bash # Install dependencies npm install # Run in development npm run dev # Build npm run build # Test rate limits npm run test:rate-limit # Test with current environment npm run test:rate-limit:anon # Test anonymous mode (10 rpm) npm run test:rate-limit:app # Test app-only mode (60 rpm) npm run test:rate-limit:auth # Test authenticated mode (100 rpm) # Lint npm run lint # Type check npm run typecheck ``` ### Requirements - Node.js >= 18.0.0 - npm or yarn - TypeScript 5.5+ ## Contributing PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. We keep things simple: - No fake analytics - Clean, typed code - Clear documentation - Fast responses ## Support - 🐛 [Report bugs](https://github.com/karanb192/reddit-mcp-buddy/issues) - 💡 [Request features](https://github.com/karanb192/reddit-mcp-buddy/issues) - ⭐ [Star on GitHub](https://github.com/karanb192/reddit-mcp-buddy) ## 🔗 Related Resources ### Official MCP Resources - **[MCP Registry](https://registry.modelcontextprotocol.io)** - Official registry of MCP servers - **[MCP Specification](https://spec.modelcontextprotocol.io)** - Official Model Context Protocol specification - **[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - SDK used to build this server - **[MCP Servers Repository](https://github.com/modelcontextprotocol/servers)** - Collection of official MCP server implementations - **[Awesome MCP Servers](https://github.com/modelcontextprotocol/awesome-mcp-servers)** - Community-curated list of MCP servers ### Where to Find This Server - **[MCP Registry Direct Link](https://registry.modelcontextprotocol.io/v0/servers/5677b351-373d-4137-bc58-28f1ba0d105d)** - Direct API link to v1.1.1 - **[MCP Registry Search](https://registry.modelcontextprotocol.io)** - Search for "reddit" to find all versions - **[NPM Package](https://www.npmjs.com/package/reddit-mcp-buddy)** - Install via npm/npx - **[GitHub Repository](https://github.com/karanb192/reddit-mcp-buddy)** - Source code and issues #### View All Versions via API ```bash # Get all versions of reddit-mcp-buddy from the registry curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | jq # Get just version numbers and UUIDs 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.