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. Claude analyzing real-time sentiment about H-1B visa changes across r/cscareerquestions and r/india - What makes Reddit MCP Buddy different? - Quick Start - What can it do? - Available Tools - Au
Add this skill
npx mdskills install karanb192/reddit-mcp-buddyWell-documented MCP server providing Reddit browsing and search tools with flexible authentication tiers
1# <img src="assets/reddit-mcp-buddy-icon-white-background.png" width="48" align="center"/> Reddit MCP Buddy23### Reddit Browser for Claude Desktop and AI Assistants45A [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.67[](https://registry.modelcontextprotocol.io)8[](https://www.npmjs.com/package/reddit-mcp-buddy)9[](https://www.npmjs.com/package/reddit-mcp-buddy)10[](https://github.com/karanb192/reddit-mcp-buddy/stargazers)11[](https://opensource.org/licenses/MIT)1213## 🎬 See It In Action14151617*Claude analyzing real-time sentiment about H-1B visa changes across r/cscareerquestions and r/india*1819## Table of Contents2021- [What makes Reddit MCP Buddy different?](#what-makes-reddit-buddy-different)22- [Quick Start](#quick-start-30-seconds)23- [What can it do?](#what-can-it-do)24- [Available Tools](#available-tools)25- [Authentication](#authentication-optional)26- [Installation Options](#installation-options)27 - [Global Install](#global-install)28 - [From Source](#from-source)29 - [Using Docker](#using-docker)30 - [Claude Desktop Extension](#claude-desktop-extension)31- [Comparison with Other Tools](#comparison-with-other-tools)32- [Troubleshooting](#troubleshooting)33- [Development](#development)34- [Support](#support)35- [Related Resources](#-related-resources)3637## What makes Reddit MCP Buddy different?3839- **🚀 Zero setup** - Works instantly, no Reddit API registration needed40- **⚡ Up to 10x more requests** - Three-tier authentication system (10/60/100 requests per minute)41- **🎯 Clean data** - No fake "sentiment analysis" or made-up metrics42- **🧠 LLM-optimized** - Built specifically for AI assistants like Claude43- **📦 TypeScript** - Fully typed, reliable, and maintainable44- **✅ Proven rate limits** - Thoroughly tested authentication tiers with verification tools4546## Quick Start (30 seconds)4748### For Claude Desktop - Desktop Extension (Easiest!)49501. **Download**: [reddit-mcp-buddy.mcpb](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/download/reddit-mcp-buddy.mcpb)512. **Install**: Open the downloaded file523. **Done!** Reddit tools are now available in Claude5354### For Claude Desktop - NPM Method (Alternative)5556Add this to your `claude_desktop_config.json`:5758```json59{60 "mcpServers": {61 "reddit": {62 "command": "npx",63 "args": ["-y", "reddit-mcp-buddy"]64 }65 }66}67```6869### For Claude Code7071Run this command to add the MCP server (user scope):7273```bash74claude mcp add --transport stdio reddit-mcp-buddy -s user -- npx -y reddit-mcp-buddy75```7677### For Other MCP Clients7879Use the NPM method: `npx -y reddit-mcp-buddy`8081## What can it do?8283Ask your AI assistant to:8485- 📊 **"What's trending on Reddit?"** - Browse hot posts from r/all86- 🔍 **"Search for discussions about AI"** - Search across all subreddits87- 💬 **"Get comments from this Reddit post"** - Fetch post with full comment threads88- 👤 **"Analyze user spez"** - Get user history, karma, and activity89- 📚 **"Explain Reddit karma"** - Understand Reddit terminology9091## Available Tools9293### `browse_subreddit`94Browse posts from any subreddit with sorting options.95```96- Subreddit:97 - "all" - entire Reddit frontpage98 - "popular" - trending across Reddit99 - Any specific subreddit (e.g., "technology", "programming", "science")100- Sort by: hot, new, top, rising, controversial101- Time range: hour, day, week, month, year, all (for top/controversial sort)102- Include subreddit info: Optional flag for subreddit metadata103```104105### `search_reddit`106Search across Reddit or specific subreddits.107```108- Query: Your search terms109- Filter by: subreddit, author, time, flair110- Sort by: relevance, hot, top, new, comments111```112113### `get_post_details`114Get a post with all its comments.115```116- Input:117 - Reddit URL (supports multiple formats), OR118 - Post ID alone (will auto-detect subreddit, 2 API calls), OR119 - Post ID + subreddit (most efficient, 1 API call)120- Supported URL formats:121 - reddit.com, www.reddit.com122 - old.reddit.com, new.reddit.com123 - np.reddit.com (No Participation links)124 - m.reddit.com (mobile links)125 - redd.it short URLs126 - URLs with query params (?utm_source=...) or fragments (#comment)127- Options: comment sorting, depth, link extraction128```129130### `user_analysis`131Analyze a Reddit user's profile.132```133- Username: Any Reddit user134- Returns: karma, posts, comments, active subreddits135```136137### `reddit_explain`138Get explanations of Reddit terms.139```140- Terms: karma, cake day, AMA, ELI5, etc.141```142143## Authentication (Optional)144145Want more requests? Add Reddit credentials to your Claude Desktop config:146147### Setup Steps1481491. **Go to** https://www.reddit.com/prefs/apps1502. **Click** "Create App" or "Create Another App"1513. **Fill out the form:**152 - **Name**: Any name (e.g., "reddit-mcp-buddy")153 - **App type**: Select **"script"** (CRITICAL for 100 rpm!)154 - **Description**: Optional155 - **About URL**: Leave blank156 - **Redirect URI**: `http://localhost:8080` (required but unused)1574. **Click** "Create app"1585. **Find your credentials:**159 - **Client ID**: The string under "personal use script"160 - **Client Secret**: The secret string1616. **Update your Claude Desktop config:**162163```json164{165 "mcpServers": {166 "reddit": {167 "command": "npx",168 "args": ["-y", "reddit-mcp-buddy"],169 "env": {170 "REDDIT_CLIENT_ID": "your_client_id",171 "REDDIT_CLIENT_SECRET": "your_client_secret",172 "REDDIT_USERNAME": "your_username",173 "REDDIT_PASSWORD": "your_password"174 }175 }176 }177}178```179180### Three-Tier Authentication System181182Reddit MCP Buddy supports three authentication levels, each with different rate limits:183184| Mode | Rate Limit | Required Credentials | Best For |185|------|------------|---------------------|----------|186| **Anonymous** | 10 req/min | None | Testing, light usage |187| **App-Only** | 60 req/min | Client ID + Secret | Regular browsing |188| **Authenticated** | 100 req/min | All 4 credentials | Heavy usage, automation |189190#### How It Works:191- **Anonymous Mode**: Default mode, no setup required, uses public Reddit API192- **App-Only Mode**: Uses OAuth2 client credentials grant (works with both script and web apps)193- **Authenticated Mode**: Uses OAuth2 password grant (requires script app type)194195**Important Notes**:196- Script apps support BOTH app-only (60 rpm) and authenticated (100 rpm) modes197- Web apps only support app-only mode (60 rpm maximum)198- For 100 requests/minute, you MUST use a script app with username + password199200## Privacy & Data Handling201202Reddit MCP Buddy is designed with privacy and transparency in mind. Here's how your data is handled:203204### Data Collection205- **Reddit API Data**: The server fetches public Reddit content (posts, comments, user profiles) through Reddit's official API206- **No Tracking**: We don't collect, store, or transmit any analytics, telemetry, or usage data207- **No Third Parties**: All data flows directly between your machine, Reddit's API, and your AI assistant208209### Local Storage210- **Authentication Credentials** (optional):211 - Stored locally in `~/.reddit-mcp-buddy/auth.json` when using `--auth` CLI setup212 - Passwords are **never** written to disk - only used in-memory for OAuth token exchange213 - Environment variables (recommended for Claude Desktop) are never persisted by this server214- **Cache Data**:215 - Reddit API responses are temporarily cached in memory to improve performance216 - Cache size limited to 50MB maximum217 - All cache data is cleared when the server stops218 - Can be disabled with `REDDIT_BUDDY_NO_CACHE=true`219220### Data Transmission221- **Reddit API Only**: Your credentials are only sent to Reddit's official OAuth endpoints (`https://oauth.reddit.com` and `https://www.reddit.com`)222- **No External Services**: No data is sent to any other external services, analytics platforms, or third parties223- **Local Processing**: All data processing happens locally on your machine224225### Security Notes226- **Read-Only Operations**: All tools are read-only - the server never posts, comments, or modifies any Reddit content227- **Credential Safety**:228 - OAuth tokens are stored in memory and refreshed automatically229 - Client secrets are treated as sensitive and never logged230 - Use environment variables in Claude Desktop config for maximum security231- **Open Source**: Full source code is available at https://github.com/karanb192/reddit-mcp-buddy for security auditing232233### GDPR & Privacy Compliance234- **No Personal Data Collection**: We don't collect or process any personal data beyond what's necessary to authenticate with Reddit's API235- **User Control**: You control all credentials and can delete `~/.reddit-mcp-buddy/auth.json` at any time236- **Right to Erasure**: Simply delete the auth file or uninstall the server to remove all local data237238### Questions or Concerns?239If you have any privacy questions or concerns, please [open an issue](https://github.com/karanb192/reddit-mcp-buddy/issues) on GitHub.240241## Testing & Development242243### Testing Your Rate Limits244245Reddit MCP Buddy includes comprehensive testing tools to verify your authentication is working correctly:246247```bash248# Clone the repository first249git clone https://github.com/karanb192/reddit-mcp-buddy.git250cd reddit-mcp-buddy251npm install252253# Test with your current environment settings254npm run test:rate-limit255256# Test specific authentication modes257npm run test:rate-limit:anon # Test anonymous mode (10 rpm)258npm run test:rate-limit:app # Test app-only mode (60 rpm)259npm run test:rate-limit:auth # Test authenticated mode (100 rpm)260```261262The rate limit tester will:263- Start a local server instance264- Make rapid API requests to test rate limits265- Display a real-time progress bar266- Confirm which authentication tier you're using267- Show exactly when rate limiting kicks in268269### Interactive Authentication Setup (for local testing only)270271For local development and testing, you can set up authentication interactively:272```bash273npx -y reddit-mcp-buddy --auth274```275276This 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.277278### Testing with HTTP Mode279280To test the server directly in your terminal:281```bash282# Run in HTTP mode on port 3000283npx -y reddit-mcp-buddy --http284285# Or with custom port286REDDIT_BUDDY_PORT=8080 npx -y reddit-mcp-buddy --http287```288289**Note:** The server runs in stdio mode by default (for Claude Desktop). Use `--http` flag for testing with Postman MCP or direct API calls.290291### Global Install292```bash293npm install -g reddit-mcp-buddy294reddit-buddy --http # For testing295```296297### From Source298```bash299git clone https://github.com/karanb192/reddit-mcp-buddy.git300cd reddit-mcp-buddy301npm install302npm run build303npm link304```305306### Using Docker307```bash308docker run -it karanb192/reddit-mcp-buddy309```310311### Claude Desktop Extension312313For one-click installation in Claude Desktop, download the pre-built extension:314315**📦 [Download reddit-mcp-buddy.mcpb](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/download/reddit-mcp-buddy.mcpb)**316317**Installation:** Simply open the downloaded `.mcpb` file - Claude Desktop will automatically install the extension and the Reddit tools will be immediately available.318319#### Build from Source (Optional)320321If you prefer to build the extension yourself:322```bash323git clone https://github.com/karanb192/reddit-mcp-buddy.git324cd reddit-mcp-buddy325./scripts/build-mcpb.sh326```327328**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).329330## Comparison with Other Tools331332| Feature | Reddit MCP Buddy | Other MCP Tools |333|---------|-------------|----------------|334| **Zero Setup** | ✅ Works instantly | ❌ Requires API keys |335| **Max Rate Limit** | ✅ 100 req/min proven | ❓ Unverified claims |336| **Language** | TypeScript/Node.js | Python (most) |337| **Tools Count** | 5 (focused) | 8-10 (redundant) |338| **Fake Metrics** | ✅ Real data only | ❌ "Sentiment scores" |339| **Search** | ✅ Full search | Limited or none |340| **Caching** | ✅ Smart caching | Usually none |341| **LLM Optimized** | ✅ Clear params | Confusing options |342| **Rate Limit Testing** | ✅ Built-in tools | ❌ No verification |343344## Rate Limits345346| Mode | Requests/Minute | Cache TTL | Setup Required |347|------|----------------|-----------|----------------|348| Anonymous | 10 | 15 min | None |349| App-only | 60 | 5 min | Client ID + Secret |350| Authenticated | 100 | 5 min | All credentials |351352## Why Reddit MCP Buddy?353354### What others do wrong:355- ❌ **Fake metrics** - "sentiment scores" that are just keyword counting356- ❌ **Complex setup** - Requiring API keys just to start357- ❌ **Bloated responses** - Returning 100+ fields of Reddit's raw API358- ❌ **Poor LLM integration** - Confusing parameters and unclear descriptions359360### What we do right:361- ✅ **Real data only** - If it's not from Reddit's API, we don't make it up362- ✅ **Clean responses** - Only the fields that matter363- ✅ **Clear parameters** - LLMs understand exactly what to send364- ✅ **Fast & cached** - Responses are instant when possible365366## Examples367368### Your AI can now answer:369370**"What are the top posts about GPT-4 today?"**371```372→ search_reddit with query="GPT-4", time="day", sort="top"373```374375**"Show me what's trending in technology"**376```377→ browse_subreddit with subreddit="technology", sort="hot"378```379380**"What do people think about this article?"**381```382→ search_reddit with the article URL to find discussions383```384385**"Analyze the user DeepFuckingValue"**386```387→ user_analysis with username="DeepFuckingValue"388```389390**"Get the comments from this Reddit post"**391```392→ get_post_details with url="https://reddit.com/r/..."393```394395**"What's trending across all of Reddit?"**396```397→ browse_subreddit with subreddit="all", sort="hot"398```399400## Troubleshooting401402### Common Issues403404**"Can't achieve 100 requests/minute"**405- Ensure your app type is **"script"** not "web" or "installed"406- Script apps created by one account can only authenticate as that same account407- Run `npm run test:rate-limit:auth` to verify (requires cloning the repo)408- If still failing, create a new script app while logged into the authenticating account409410**"Command not found" error**411```bash412# Ensure npm is installed413node --version414npm --version415416# Try with full npx path417$(npm bin -g)/reddit-mcp-buddy418```419420**Rate limit errors**421- Without auth: Limited to 10 requests/minute422- With app credentials only: 60 requests/minute423- With full authentication: 100 requests/minute424- Solution: Add Reddit credentials (see [Authentication](#authentication-optional))425426**"Subreddit not found"**427- Check spelling (case-insensitive)428- Some subreddits may be private or quarantined429- Try "all" or "popular" instead430431**Connection issues**432- Reddit may be down (check https://www.redditstatus.com)433- Firewall blocking requests434- Try restarting the MCP server435436### Environment Variables437438#### Authentication Variables439| Variable | Description | Required | Rate Limit |440|----------|-------------|----------|------------|441| `REDDIT_CLIENT_ID` | Reddit app client ID | No | 60 req/min (with secret) |442| `REDDIT_CLIENT_SECRET` | Reddit app secret | No | 60 req/min (with ID) |443| `REDDIT_USERNAME` | Reddit account username | No | 100 req/min (with all 4) |444| `REDDIT_PASSWORD` | Reddit account password | No | 100 req/min (with all 4) |445| `REDDIT_USER_AGENT` | User agent string | No | - |446447#### Server Configuration448| Variable | Description | Default |449|----------|-------------|---------|450| `REDDIT_BUDDY_HTTP` | Run as HTTP server instead of stdio | `false` |451| `REDDIT_BUDDY_PORT` | HTTP server port (when HTTP=true) | `3000` |452| `REDDIT_BUDDY_NO_CACHE` | Disable caching (always fetch fresh) | `false` |453454## Technical Details455456### Smart Caching System457458Reddit MCP Buddy includes intelligent caching to improve performance and reduce API calls:459460- **Memory Safe**: Hard limit of 50MB - won't affect your system performance461- **Adaptive TTLs**: Hot posts (5min), New posts (2min), Top posts (30min)462- **LRU Eviction**: Automatically removes least-used data when approaching limits463- **Hit Tracking**: Optimizes cache based on actual usage patterns464465This means faster responses and staying well within Reddit's rate limits, all while using minimal system resources.466467## Development468469```bash470# Install dependencies471npm install472473# Run in development474npm run dev475476# Build477npm run build478479# Run tests480npm test # Unit tests481npm run test:integration # Integration tests482npm run test:all # All tests483484# Test rate limits485npm run test:rate-limit # Test with current environment486npm run test:rate-limit:anon # Test anonymous mode (10 rpm)487npm run test:rate-limit:app # Test app-only mode (60 rpm)488npm run test:rate-limit:auth # Test authenticated mode (100 rpm)489490# Lint491npm run lint492493# Type check494npm run typecheck495```496497### Requirements498- Node.js >= 18.0.0499- npm or yarn500- TypeScript 5.5+501502## Contributing503504PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.505506We keep things simple:507- No fake analytics508- Clean, typed code509- Clear documentation510- Fast responses511512## Support513514- 🐛 [Report bugs](https://github.com/karanb192/reddit-mcp-buddy/issues)515- 💡 [Request features](https://github.com/karanb192/reddit-mcp-buddy/issues)516- ⭐ [Star on GitHub](https://github.com/karanb192/reddit-mcp-buddy)517518## 🔗 Related Resources519520### Official MCP Resources521- **[MCP Registry](https://registry.modelcontextprotocol.io)** - Official registry of MCP servers522- **[MCP Specification](https://spec.modelcontextprotocol.io)** - Official Model Context Protocol specification523- **[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - SDK used to build this server524- **[MCP Servers Repository](https://github.com/modelcontextprotocol/servers)** - Collection of official MCP server implementations525- **[Awesome MCP Servers](https://github.com/modelcontextprotocol/awesome-mcp-servers)** - Community-curated list of MCP servers526527### Where to Find This Server528- **[MCP Registry Direct Link](https://registry.modelcontextprotocol.io/v0/servers/5677b351-373d-4137-bc58-28f1ba0d105d)** - Direct API link to this server529- **[MCP Registry Search](https://registry.modelcontextprotocol.io)** - Search for "reddit" to find all versions530- **[NPM Package](https://www.npmjs.com/package/reddit-mcp-buddy)** - Install via npm/npx531- **[GitHub Repository](https://github.com/karanb192/reddit-mcp-buddy)** - Source code and issues532533#### View All Versions via API534```bash535# Get all versions of reddit-mcp-buddy from the registry536curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | jq537538# Get just version numbers and UUIDs539curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | \540 jq '.servers[] | {version, id: ._meta."io.modelcontextprotocol.registry/official".id}'541```542543## License544545MIT - Use it however you want!546547---548549Made with ❤️ for the MCP community. No venture capital, no tracking, just a good MCP server.
Full transparency — inspect the skill content before installing.