reddit-mcp

Local MCP server that turns Reddit into a research surface for Claude Desktop. Ask about travel itineraries, gear tradeoffs, "is X actually worth it" — the questions that resolve on Reddit and nowhere else.

Install

python3 -m venv .venv
.venv/bin/pip install -e .

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "reddit": {
      "command": "/Users/jay/dev/general/reddit-mcp/.venv/bin/reddit-mcp"
    }
  }
}

Restart Claude Desktop. There is no server to start yourself — Desktop spawns the process over stdio.

Tools

Tool	Use
find_subreddits	Locate the right community first. Search quality improves sharply once scoped.
search_reddit	Find candidate threads. Optionally scoped to a subreddit.
top_posts	Better recall than search when you already know the community. listing="new" for time-sensitive things like job posts.
get_thread	Read a thread's comments — where the opinions actually are. Takes a bare id, a t3_ fullname, or a full permalink.

get_thread is budgeted: max_comments caps count, char_budget caps total size. The submission may take at most POST_BODY_SHARE (40%) of the budget, so a long guide post can never crowd the comments out.

Why the Atom feeds

Reddit closed self-service Data API registration in November 2025. New app creation now requires a valid moderation use case, which personal research is not, and there are no grandfathered credentials on this account. The public .json endpoints answer 403 "blocked by network security" to every non-browser client, on every host, from any user agent.

The .rss feeds are the one public surface that still serves plain HTTP clients. Everything here goes through them.

What that costs

Not recoverable from Atom, at any price:

• post and comment scores — no min_score filtering, and no score shown
• comment counts
• parent/child links between comments — so no max_depth, and threads read flat rather than nested

Ranking is still Reddit's own, requested via sort= and applied server-side. You lose the score numbers, not the ordering.

Rate limits

The feeds throttle hard — a cold request answers 429 more often than not and needs several seconds of backoff. The client therefore enforces a minimum interval between requests, retries with exponential backoff, and caches by URL (threads 24h, searches 6h, listings 1h). Throttling and caching are load-bearing here, not optimisations.

Tests

.venv/bin/python -m pytest

Shaping tests run against captured fixtures in fixtures/ and never touch the network. Re-capture only if the feed format changes:

python3 tests/capture_fixtures.py

If Data API access ever lands

The fetch layer (client.py) is the only module that knows about RSS. Shaping, budgets and the tool surface sit above it. Swapping in an OAuth client against oauth.reddit.com restores scores and comment nesting without touching the rest.