read-it

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 smallenough to reason over rather than dumped as raw JSON. Several Reddit accounts can be configured andselected per call.

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

Status: under construction. The HTTP, auth, rate-limiting, and configuration layers are builtand tested; the tools themselves are not finished yet. Setup below is complete and correct — youneed 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'sResponsible Builder Policystates: "Approval is required: You must request access and get explicit approval before accessingany 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 themwastes an afternoon:

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

For the second, Reddit's Developer Platform & Accessing Reddit Dataarticle 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 athttps://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 notsupported by Devvit, file a ticket." A local MCP server reading Reddit on your own behalf is not aDevvit 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 spreadingload across clients to stretch limits are all covered by the policy's transparency and access-limitclauses, 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 submittingmultiple requests for the same use case." Configuring several accounts to obtain several ratebudgets for one purpose is not a supported pattern. Multi-account support exists here forgenuinely distinct, separately-approved purposes — not to widen a limit.
• App accounts should not be mixed use. The policy states "App accounts should solely be usedto 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 anaccount whose use fits your approval, not casually at a personal one.
• Respect the limits. "You must not circumvent or exceed access limits." This server pacesitself 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 2FAcode appended as password:otp, but that code expires in about 30 seconds — so an unattended servercan never refresh its own token. Use accounts without 2FA, or a dedicated account created for APIuse.

The app type must be script. The other types use a different OAuth flow entirely and will failagainst 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 underUser 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 asnode:read-it:v<version> (by /u/<username>), which is the format Reddit mandates. SetREDDIT_<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 notsee them — including an editor or terminal you already had open. Either restart it, or hydrate thecurrent 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 willwork. 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 responseheaders rather than a hardcoded ceiling — Reddit's published figures disagree between its archivedwiki (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. Eachaccount is paced independently.

Reddit's Data API terms prohibit using API data for commercial products or services without aseparately negotiated licence. All access — commercial or not — requires prior approval under theResponsible Builder Policy;see step 1. Academic research has its own route, the Reddit for Researchers programme, and thepolicy states that "any research that uses Reddit data collected outside of the RFR Program is inviolation 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