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.

• What makes Reddit MCP Buddy different?
• Quick Start
• What can it do?
• Available Tools
• Authentication
• Installation Options
• Comparison with Other Tools
• Troubleshooting
• Development
• Support

• 🚀 Zero setup - Works instantly, no Reddit API registration needed
• ⚡ Up to 10x more requests - Optional authentication increases rate 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

Add this to your claude_desktop_config.json:

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

That's it! Reddit MCP Buddy is now available in Claude.

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 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 across Reddit or specific subreddits.

- Query: Your search terms
- Filter by: subreddit, author, time, flair
- Sort by: relevance, hot, top, new, comments

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

Analyze a Reddit user's profile.

- Username: Any Reddit user
- Returns: karma, posts, comments, active subreddits

Get explanations of Reddit terms.

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

Want more requests? Add Reddit credentials to your Claude Desktop config:

1. Go to https://www.reddit.com/prefs/apps
2. Create an app (type: script - IMPORTANT!)
3. Find your credentials:
   • Client ID: Shows under "personal use script"
   • Client Secret: The secret string on the app page
4. Update your Claude Desktop config:

{
  "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"
      }
    }
  }
}

• No auth: 10 requests/minute (default)
• Client ID + Secret only: 60 requests/minute
• With username + password: 100 requests/minute

Note: For maximum rate limits (100 req/min), you need all four credentials including username and password.

For local development and testing, you can set up authentication interactively:

npx reddit-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.

To test the server directly in your terminal:

# 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.

npm install -g reddit-mcp-buddy
reddit-buddy --http  # For testing

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

docker run -it karanb192/reddit-mcp-buddy

• ❌ 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

• ✅ 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

"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"

"Command not found" error

# 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)

"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

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.

# Install dependencies
npm install

# Run in development
npm run dev

# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Type check
npm run typecheck

• Node.js >= 18.0.0
• npm or yarn
• TypeScript 5.5+

PRs welcome! See CONTRIBUTING.md for guidelines.

We keep things simple:

• No fake analytics
• Clean, typed code
• Clear documentation
• Fast responses

• 🐛 Report bugs
• 💡 Request features
• ⭐ Star on GitHub

MIT - Use it however you want!

Made with ❤️ for the MCP community. No venture capital, no tracking, just a good MCP server.