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

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

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 Win, 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:

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

[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.

Related MCP server: Reddit MCP Server

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

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/.

Licence

MIT