# 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

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

## Connect to Claude Desktop

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

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

```bash
.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:

```bash
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.