# read-it

An MCP server that gives Claude read-only research access to Reddit's API.

Find the subreddits where a topic lives, search them, and read whole comment trees — shaped small
enough to reason over rather than dumped as raw JSON. Several Reddit accounts can be configured and
selected per call.

**The server cannot write to Reddit.** No tool posts, comments, votes, subscribes, or messages. The
capability is absent rather than merely unused, and the OAuth token requests only
`read history identity mysubreddits`.

> **Status: under construction.** The HTTP, auth, rate-limiting, and configuration layers are built
> and tested; the tools themselves are not finished yet. Setup below is complete and correct — you
> need it to record the API fixtures the remaining work is tested against.

---

## Setting up Reddit access

### 1. Request API access — approval is required

> **Creating a script app at `reddit.com/prefs/apps` is no longer sufficient on its own.** Reddit's
> [Responsible Builder Policy](https://support.reddithelp.com/hc/en-us/articles/42728983564564-Responsible-Builder-Policy)
> states: *"Approval is required: You must request access and get explicit approval before accessing
> any Reddit data through our API, and you must agree to comply with all applicable terms."*

**Two separate registrations exist, and only one of them yields API credentials.** Confusing them
wastes an afternoon:

| | What it is | What you get |
|---|---|---|
| **App registration / labelling** | Registering an app and developer profile so the account carries an App profile label | The bot label, and automated-account restrictions lifted. **No OAuth credentials.** |
| **Data API access sign-up** | The approval the Responsible Builder Policy requires | The client id and secret this server needs |

If you completed the first and `reddit.com/prefs/apps` is empty, that is expected — an app label is
not an OAuth client.

For the second, Reddit's [Developer Platform & Accessing Reddit Data](https://support.reddithelp.com/hc/en-us/articles/14945211791892-Developer-Platform-Accessing-Reddit-Data)
article says: *"To use Reddit's Data API for non-commercial purposes, you need to sign-up here"* —
and that link goes to the support request form at
<https://support.reddithelp.com/hc/en-us/requests/new>, not to a self-serve page.

For non-commercial development the policy points at Devvit first and says *"if your use case is not
supported by Devvit, file a ticket."* A local MCP server reading Reddit on your own behalf is not a
Devvit app, so the ticket is the route. Commercial use needs separate explicit written approval.

There is a draft of that request in [`docs/reddit-api-access-request.md`](docs/reddit-api-access-request.md).

Do not work around this. Unauthenticated scraping, undisclosed extra registrations, or spreading
load across clients to stretch limits are all covered by the policy's transparency and access-limit
clauses, and put the Reddit accounts involved at risk.

Once access is granted, the client id and secret go in the variables below.

### 2. Policy constraints that shape how you configure this

Read these before deciding how many accounts to configure.

- **One request per use case.** The policy prohibits *"registering multiple accounts or submitting
  multiple requests for the same use case."* Configuring several accounts to obtain several rate
  budgets for one purpose is not a supported pattern. Multi-account support exists here for
  genuinely distinct, separately-approved purposes — not to widen a limit.
- **App accounts should not be mixed use.** The policy states *"App accounts should solely be used
  to perform app functions (no mixed use accounts)."* This bears directly on the `reddit_me` tool,
  which reads the authenticated account's own saved posts, subscriptions and votes. Point it at an
  account whose use fits your approval, not casually at a personal one.
- **Respect the limits.** *"You must not circumvent or exceed access limits."* This server paces
  itself from Reddit's own rate-limit headers rather than a hardcoded ceiling.

### 3. Two constraints that will otherwise waste your time

**No account may have two-factor authentication enabled.** Reddit's password grant accepts a 2FA
code appended as `password:otp`, but that code expires in about 30 seconds — so an unattended server
can never refresh its own token. Use accounts without 2FA, or a dedicated account created for API
use.

**The app type must be `script`.** The other types use a different OAuth flow entirely and will fail
against this server.

### 4. Set the environment variables

Credentials are read from environment variables. On Windows, set them as **User** variables:
press <kbd>Win</kbd>, search *"Edit environment variables for your account"*, and add them under
**User variables**.

Accounts are declared by label. Each label `LABEL` implies a `REDDIT_<LABEL>_*` group:

| Variable | Example | Notes |
|---|---|---|
| `REDDIT_ACCOUNTS` | `main,alt` | comma-separated labels; letters, digits, underscores only |
| `REDDIT_DEFAULT_ACCOUNT` | `main` | optional — defaults to the first label |
| `REDDIT_MAIN_CLIENT_ID` | | from step 1 |
| `REDDIT_MAIN_CLIENT_SECRET` | | from step 1 |
| `REDDIT_MAIN_USERNAME` | | the Reddit username, without `u/` |
| `REDDIT_MAIN_PASSWORD` | | that account's password |
| `REDDIT_ALT_*` | | the same four for each further account |

A single account is fine — set `REDDIT_ACCOUNTS=main` and one group.

You do **not** need to set a User-Agent. It is derived per account as
`node:read-it:v<version> (by /u/<username>)`, which is the format Reddit mandates. Set
`REDDIT_<LABEL>_USER_AGENT` only if you want to override it; a malformed one is rejected at startup.

See [`.env.example`](.env.example) for the full shape.

### 5. Windows: make a running process see the new variables

Windows writes User variables to the registry, so **any process started before you set them will not
see them** — including an editor or terminal you already had open. Either restart it, or hydrate the
current PowerShell session from the registry:

```powershell
[Environment]::GetEnvironmentVariables('User').GetEnumerator() |
  Where-Object { $_.Key -like 'REDDIT_*' } |
  ForEach-Object { Set-Item -Path "env:$($_.Key)" -Value $_.Value }
```

Child processes inherit the hydrated session, so `npm` and `npx` commands run from that shell will
work. Re-run it in any new shell.

---

## Rate limits and terms

Request pacing is driven by Reddit's own `X-Ratelimit-Remaining` and `X-Ratelimit-Reset` response
headers rather than a hardcoded ceiling — Reddit's published figures disagree between its archived
wiki (60 requests/minute) and the current free Data API tier (100 queries/minute per OAuth client id,
averaged over a rolling 10-minute window), so the headers are the only trustworthy source. Each
account is paced independently.

Reddit's Data API terms prohibit using API data for commercial products or services without a
separately negotiated licence. All access — commercial or not — requires prior approval under the
[Responsible Builder Policy](https://support.reddithelp.com/hc/en-us/articles/42728983564564-Responsible-Builder-Policy);
see step 1. Academic research has its own route, the Reddit for Researchers programme, and the
policy states that *"any research that uses Reddit data collected outside of the RFR Program is in
violation of this policy."*

---

## Development

```bash
npm install
npm test          # offline — runs against recorded fixtures, never the network
npm run typecheck
npm run build
```

`npm run smoke` exercises every tool against live Reddit and needs the credentials above.

Design and implementation notes live in [`docs/superpowers/`](docs/superpowers/).

## Licence

MIT