reddit-mcp

An MCP server over the Reddit API, backed by a self-owned OAuth2 app. Unlike the read-only servers in this set, this one can act as the account — post, comment, vote, and send private messages — so it is worth being deliberate about what you ask it to do.

Runs over stdio, registered in ~/.claude.json as reddit.

Tools

Read

Tool	Purpose
reddit_get_me	The authenticated account's own profile
reddit_get_user	Another user's public profile
reddit_get_user_activity	A user's recent posts and comments
reddit_get_subreddit_posts	Listing for a subreddit (hot/new/top/rising)
reddit_get_post	A single post plus its comment tree
reddit_search	Search across Reddit or within one subreddit
reddit_get_inbox	Private messages and inbox replies

Write — these have real, public consequences

Tool	Purpose
reddit_submit_post	Create a new post in a subreddit
reddit_submit_comment	Reply to a post or comment
reddit_vote	Up/down/clear vote on a post or comment
reddit_send_message	Send a private message to a user
reddit_mark_read	Mark inbox items read

The write tools post under your real account, publicly and attributably. Reddit's spam and vote-manipulation rules apply to API traffic exactly as they do to browser traffic, and account bans follow the account, not the app.

Auth

OAuth2 with a refresh token, stored in credentials/token.json (gitignored). Reddit does not rotate refresh tokens, so the stored one stays valid indefinitely — access tokens are refreshed automatically ~60s before expiry.

npm run authorize    # one-time browser consent, writes credentials/token.json
npm run check-auth   # verify the stored token still works

Setup

Requires Node 20+.

1. Create a script app at reddit.com/prefs/apps.

2. Save its id and secret to credentials/client_secret.json — see credentials/client_secret.example.json for the shape. credentials/ is git-ignored.

3. Identify yourself to Reddit. The default User-Agent contains a placeholder, and Reddit throttles generic agents hard, so set one of:

   REDDIT_USERNAME=your_reddit_username        # fills in the /u/ segment
   REDDIT_USER_AGENT="platform:app:v1.0.0 (by /u/you)"   # or replace it wholesale
   

4. Authorize and register:

   npm ci
   npm run authorize
   claude mcp add reddit -- node <path>/reddit-mcp/src/index.js
   

Tests

npm test

Registration, the fullname-prefix helper, and User-Agent construction. No network and no credentials, so it is safe in CI.

Layout

src/auth.js            token load, refresh, caching
src/reddit.js          all tool registrations
src/index.js           McpServer construction + stdio transport
scripts/authorize.js   one-time OAuth consent flow
scripts/check-token.js token health check

Notes

• Reddit requires a descriptive, unique User-Agent; a generic one gets 429s regardless of rate.
• Fullnames are prefixed type IDs (t3_ post, t1_ comment, t5_ subreddit). reddit_vote wants the fullname, not the short ID from a URL.