Reddit MCP Server

Your AI, plugged into Reddit. No API key. No login. Just the raw feed.

Give Claude — or any MCP client — real-time access to Reddit: browse subreddits, pull comment threads, mine startup ideas and pain points. Built on FastMCP and Playwright, it scrapes the public web interface with a fast, headless browser. The result: live Reddit data, straight from the source, with zero setup cost.

You:  "What are people complaining about in r/SaaS this week?"
AI:   ▸ 214 posts scanned · 37 pain points found · score 1260 "Paying for
      overpriced subscriptions is ridiculous" · 8 ideas over 1000 points

---

What's inside

• 🔍 Search & browse — scan one or many subreddits with native sorting, time filters and keyword filtering
• 💬 Comments & details — threaded comment trees with authors, scores and depth, plus full post bodies
• 📊 Subreddit & user intel — description, active users, top posts; any user's public posts and karma
• 🚀 Business opportunity radar — scores posts for startup/pain-point potential (see the algorithm)
• ⚡ Built for speed — one shared browser reused across calls, an in-memory TTL cache, asset blocking, retries with backoff, anti-bot detection

Table of Contents

1. 10-second demo
2. Available Tools
3. Quick Start
4. Client Configuration
   • Claude Desktop / Claude Code
5. Opportunity Scoring Algorithm
6. Configuration
7. Development
8. Docker
9. Troubleshooting & Limitations
10. Contributing · Security · License

10-second demo

Ask your assistant in plain language — it speaks MCP natively:

"Search Reddit for 'best mechanical keyboard 2025' from the last month."

{
  "total_results": 25,
  "query": "best mechanical keyboard 2025",
  "posts": [
    {
      "title": "The Keychron Q3 is criminally underrated",
      "score": 812,
      "num_comments": 143,
      "author": "keeblover42",
      "url": "https://www.reddit.com/r/MechanicalKeyboards/comments/...",
      "post_type": "self"
    }
  ]
}

"Analyze r/SaaS and r/Entrepreneur for startup pain points."

{
  "total_posts_scanned": 214,
  "high_score_ideas": 8,
  "ideas": [
    {
      "title": "Paying for overpriced subscriptions is ridiculous — someone should make a smart subscription manager",
      "opportunity_score": 1260,
      "matched_keywords": ["pay", "subscription", "should exist", "problem"],
      "url": "https://www.reddit.com/r/SaaS/comments/..."
    }
  ]
}

Available Tools

Tool	Parameters	Description
search_reddit	subreddits (list), sort, time_filter, limit, keywords (list)	Browse posts from specific subreddits with sorting.
search_reddit_query	query (str), sort, time_filter, subreddit, limit	Perform a global keyword search across Reddit.
get_post_comments	post_url (str), limit	Extract threaded comments with hierarchical depth.
get_post_details	post_url (str)	Get full details: selftext, link, flair, metadata.
get_subreddit_info	subreddit (str)	Name, description, active users and top posts.
get_user_posts	username (str), sort, limit	Browse a user's public posts and karma.
get_trending_posts	limit, time_filter	Get the current top posts of r/popular.
analyze_opportunities	subreddits (list), min_score, limit, keywords (list), sort, time_filter	Identify high-potential SaaS/startup pain points.
health_check	—	Verify the server is alive (no network access).

Quick Start

git clone https://github.com/Simonc44/Reddit-MCP-Server.git
cd Reddit-MCP-Server

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium                          # one-time browser download

That's it — the server is ready. Point your MCP client at python /path/to/server.py.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json (use absolute paths):

{
  "mcpServers": {
    "reddit-mcp": {
      "command": "/path/to/your/virtualenv/bin/python",
      "args": ["/path/to/reddit-mcp-server/server.py"]
    }
  }
}

Windows: use double backslashes in your paths.

Claude Code

claude mcp add reddit-mcp -- python /path/to/reddit-mcp-server/server.py

Opportunity Scoring Algorithm

$$Score = (Upvotes \times 2) + (Comments \times 3)$$

With multipliers and bonuses:

• High engagement — comments/upvotes ratio $> 0.3$ → ×1.3 (or ×1.15 if $> 0.15$)
• Monetization keywords — $+15$ per match (pay, subscription, SaaS, pricing, …)
• Pain-point keywords — $+20$ per match (problem, frustrated, broken, wish, hate, …)
• Dual-category bonus — both categories detected → overall ×1.25

Keyword matching respects word boundaries (pay matches paying, not paywall), and every idea includes its matched_keywords so the AI can explain its reasoning.

Configuration

Every knob is an environment variable — no code changes needed:

Variable	Default	Description
REDDIT_HEADLESS	true	Run Chromium headless (false to watch the browser).
REDDIT_VIEWPORT_WIDTH / REDDIT_VIEWPORT_HEIGHT	1280 / 900	Browser viewport.
REDDIT_USER_AGENT	modern Chrome UA	User-agent sent to Reddit.
REDDIT_NAV_TIMEOUT_MS	45000	Navigation timeout (ms).
REDDIT_WAIT_TIMEOUT_MS	15000	Content wait timeout (ms).
REDDIT_REQUEST_DELAY	1.5	Pause (s) between subreddit requests — be polite to Reddit.
REDDIT_MAX_SCROLLS	4	Scroll iterations to trigger lazy-loaded content.
REDDIT_MAX_RETRIES	3	Retry attempts per page load (exponential backoff).
REDDIT_RETRY_BACKOFF	2.0	Base backoff (s) between retries.
REDDIT_CACHE_TTL	300	TTL (s) of the in-memory cache for listings (0 disables).
REDDIT_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR).

Development

uv sync --extra dev      # reproducible env in .venv/ (uv is optional — pip works too)
make lint                # ruff
make typecheck           # mypy (server + tests)
make test                # pytest — 133 offline unit tests
make coverage            # pytest + coverage gate (100 %)
make test-live           # live tests against real reddit.com (needs Chromium)
make run                 # start the MCP server

Tests are a first-class citizen here:

• tests/test_server.py, tests/test_scraper.py, tests/test_browser.py — 133 offline tests using fake Playwright objects: 100 % coverage, no browser, no network.
• tests/test_integration.py — live end-to-end tests against the real Reddit website (opt-in: REDDIT_LIVE_TESTS=1 pytest -m integration).

CI (.github/workflows/ci.yml) runs ruff, mypy and the coverage gate on Python 3.10–3.12, plus an opt-in live job.

Docker

docker build -t reddit-mcp-server .
docker run -i --rm reddit-mcp-server

Chromium is installed inside the image, and the server runs as an unprivileged user.

Troubleshooting & Limitations

• Rate limits & IP blocks — heavy scraping can trigger Reddit's anti-bot (HTTP 429 / login redirects). The server retries with backoff and detects them; increase REDDIT_REQUEST_DELAY if you get blocked.
• Dynamic DOM — this is a scraper, not an API: if Reddit changes its frontend, selectors may break. The live test suite exists to catch exactly that — run it before opening an issue.
• Member counts — Reddit's anonymous UI no longer exposes a subreddit's total member count; get_subreddit_info returns members: null when unavailable (other stats come from the structured page header and are reliable).
• Speed — first call of a session launches Chromium (5–30 s); subsequent calls reuse the shared browser and cache.
• No private auth — public-facing pages only; no account login.

Contributing

Contributions are very welcome — improving selectors, adding tools, refining docs. See CONTRIBUTING.md.

Security

Found a vulnerability? Report it privately — see SECURITY.md.

License

MIT © 2026 Simon Chusseau