Reddit Buddy MCP

🤖 Reddit Buddy MCP

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.

What makes Reddit Buddy different?

🚀 Zero setup - Works instantly, no Reddit API registration needed
⚡ 10x faster - Optional authentication gives you 10x more requests
🎯 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

Quick Start (30 seconds)

For Claude Desktop

Add this to your claude_desktop_config.json:

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

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

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 10x more requests? Add Reddit credentials:

Go to https://www.reddit.com/prefs/apps
Create an app (type: script)
Add credentials to .env:

REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USER_AGENT=YourApp/1.0

Update your Claude config:

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["reddit-buddy-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USER_AGENT": "YourApp/1.0"
      }
    }
  }
}

Installation Options

Testing with HTTP Mode (for developers)

To test the server directly in your terminal:

# Run in HTTP mode on port 3000
npx @karanb192/reddit-buddy-mcp --http

# Or with custom port
REDDIT_BUDDY_PORT=8080 npx @karanb192/reddit-buddy-mcp --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 @karanb192/reddit-buddy-mcp
reddit-buddy --http  # For testing

From Source

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

Using Docker

docker run -it karanb192/reddit-buddy-mcp

Comparison with Other Tools

Feature	Reddit Buddy	Other MCP Tools
Zero Setup	✅ Works instantly	❌ Requires API keys
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 Limits

Mode	Requests/Minute	Cache TTL
Anonymous	10	15 min
Authenticated	100	5 min

Why Reddit 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

"Command not found" error

# Ensure npm is installed
node --version
npm --version

# Try with full npx path
$(npm bin -g)/reddit-buddy-mcp

Rate limit errors

Without auth: Limited to 10 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

Environment Variables

Variable	Description	Required	Default
`REDDIT_CLIENT_ID`	Reddit app client ID	No	-
`REDDIT_CLIENT_SECRET`	Reddit app secret	No	-
`REDDIT_USER_AGENT`	User agent string	No	`RedditBuddy/1.0`
`REDDIT_BUDDY_HTTP`	Run as HTTP server	No	`false`
`REDDIT_BUDDY_NO_CACHE`	Disable caching (always fetch fresh)	No	`false`

Technical Details

Smart Caching System

Reddit 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+

Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

We keep things simple:

No fake analytics
Clean, typed code
Clear documentation
Fast responses

Support

License

MIT - Use it however you want!

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