# Reddit MCP — read-only monitoring for two accounts

An MCP server that lets Claude watch Reddit for you: inbox, post
performance, silent removals, subreddit intel, timing analytics, and
market scans. **Strictly read-only** — the client physically refuses every
write endpoint except marking your own inbox messages read. It cannot
post, vote, comment, or delete, even if asked.

## The 18 tools

| Group | Tools |
|---|---|
| Inbox | `get_inbox`, `get_messages`, `mark_read` |
| Post performance | `get_my_posts`, `get_post_details`, `check_post_visibility` |
| Subreddit activity | `get_subreddit_feed`, `get_subreddit_rules`, `get_subreddit_sidebar` |
| Mentions & discovery | `search_mentions`, `search_subreddit` |
| Account health | `get_account_stats`, `check_shadowban`, `get_karma_breakdown` |
| Timing & analytics | `get_post_timing_data`, `get_subreddit_activity_pattern` |
| Market scan | `get_competitor_posts`, `get_trending_flairs` |

Every tool takes an optional `account` parameter: `"account_1"` or
`"account_2"`. Omitted = the default from `.env`.

## Public mode — works with zero credentials

The subreddit, search, and market-scan tools also run **without any API
credentials at all**: pass `account="public"`, or just configure nothing
and they fall back automatically. Public mode reads Reddit's public JSON
the way a logged-out browser does — no login, no OAuth, no account
anywhere in the loop.

The honest status (verified August 2026): Reddit now returns 403 to
unauthenticated `.json` and `.rss` requests even from residential IPs —
the logged-out programmatic surface is effectively closed platform-wide.
Public mode remains in the codebase in case that policy relaxes, but as
of this writing, **all live use of this server requires approved API
credentials.** The account tools (inbox, messages, my-posts, karma,
shadowban) always required credentials regardless — there is no keyless
way to read a mailbox, here or anywhere.

Notes on the clever ones:

- **`check_shadowban`** uses the *other* configured account as an
  authenticated witness — a shadowbanned account looks normal to itself,
  so a second set of eyes is the only honest check.
- **`check_post_visibility`** walks the subreddit's `/new` listing back to
  your post's timestamp. On the profile but not in the listing = silently
  removed.
- **`get_my_posts`, `get_post_details`, and `get_post_timing_data`** append
  metric snapshots to `data/snapshots.jsonl` as a side effect. Reddit only
  reports scores *right now*; this file is the over-time record the future
  ad-assembly skill will feed on. Delete it any time — it regrows.
- **`search_mentions`** searches posts only. Reddit's search API does not
  index comments; comment mentions of `u/yourname` arrive via `get_inbox`.

## Setup

### 1. Register a script app for EACH account

While logged in **as that account** in a browser:

1. Go to <https://www.reddit.com/prefs/apps> → "create another app..."
2. Name: anything. Type: **script** (the radio button — this is the one
   choice that matters). Redirect uri: `http://localhost:8080` (required
   by the form, never used).
3. After creating: the string **under the app name** is the `client_id`;
   the string labeled **secret** is the `client_secret`.

Requirements per account: 2FA **off** (script auth sends username +
password directly), "I am over 18" enabled in Reddit preferences, and a
verified email (recovery path if Reddit ever questions a login).

### 2. Install

```bash
cd reddit-mcp
uv venv .venv
uv pip install -p .venv/bin/python -e .
```

(Or plain pip: `python3 -m venv .venv && .venv/bin/pip install -e .`)

### 3. Credentials

**Desktop:** copy `.env.example` to `.env` in this folder and fill in the
four values per account. `.env` is gitignored; it never leaves the machine.

**Cloud (Cowork / Claude Code on the web):** don't create a `.env` — put
the same variables into the environment's settings (the environment
variables section of the Cowork environment config). Real env vars win
over the `.env` file, so both rooms work with the same code.

### 4. Wire into Claude Desktop

`claude_desktop_config.json` → `mcpServers`:

```json
{
  "reddit-monitor": {
    "command": "/absolute/path/to/reddit-mcp/.venv/bin/python",
    "args": ["-m", "reddit_mcp.server"]
  }
}
```

For Claude Code (CLI), from this folder:

```bash
claude mcp add reddit-monitor -- .venv/bin/python -m reddit_mcp.server
```

## Rate limits & bot-likeness

- Reddit allows 60 requests/minute per OAuth client; this server caps
  itself at 55 per account with a sliding window, obeys Reddit's
  `X-Ratelimit-*` headers, and backs off automatically on 429.
- The access token is cached until expiry — one login per hour of use,
  not one per call.
- User-Agent follows Reddit's required format:
  `python:iris-reddit-mcp:0.1.0 (by /u/<username>)`. Reading your own
  data through the official API with a proper UA is what the API is for.

## Tests

```bash
uv pip install -p .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -v
```

31 tests, all named in plain English — read the list like a checklist of
promises. No test touches the real Reddit; all HTTP is mocked.

## Reddit API access note (2026)

Since Reddit's Responsible Builder Policy (Nov 2025), new OAuth app
credentials require requesting access through Reddit's Data API form.
This server is designed to satisfy that policy: read-only, personal-use,
own-account monitoring, rate-limited, with a hard-coded refusal of every
write endpoint. Until credentials are granted, public mode works today.