Reddit Buddy MCP

🚀 Reddit MCP Buddy

A Reddit browser for Claude Desktop and AI assistants, enabling seamless Reddit interaction without API keys.

🚀 Quick Start

For Claude Desktop

Add the following 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.

✨ Features

• 🚀 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.

📦 Installation Options

For local development and testing

• Interactive Authentication Setup:

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.

• Testing with HTTP Mode:

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

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

• 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

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

📚 Documentation

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

Rate Limits

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

Comparison with Other Tools

Rate Limits

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.

Troubleshooting

Common Issues

• "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](#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

Server Configuration

🔧 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

# 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

Requirements

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

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)

📄 License

MIT - Use it however you want!

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