reddit-mcp

An MCP server for a single Reddit account, built on Reddit's OAuth API via PRAW. Tools are gated into read, write and full tiers.

Setup

1. Register a Reddit app

Create an app at https://www.reddit.com/prefs/apps with type installed app and redirect URI http://localhost:8080/callback.

The client ID is the string under the app name, not the app name.

2. Install

./bin/setup.sh

3. Authorize

./.venv/bin/python bin/auth.py --scope write

Opens Reddit's consent page and writes a refresh token to ~/.config/reddit-mcp/credentials.json (mode 0600). No password is stored, and the grant is revocable at https://www.reddit.com/prefs/apps.

4. Register with an MCP client

claude mcp add reddit -- /path/to/reddit-mcp/.venv/bin/python \
  /path/to/reddit-mcp/src/server.py

Permission tiers

REDDIT_MCP_SCOPE selects the tier. Default is write.

Tier	Adds	Tools
read	Browsing, search, inbox, saved, history	9
write	Submitting, replying, editing, deleting	14
full	Voting, saving, subscribing, moderation	19

Tools are registered per tier, not checked at call time, so lower tiers omit the higher tools from the tool list entirely.

bin/auth.py --scope sets the OAuth scopes on the token itself, independently of the runtime tier. A token narrower than the tier gives a second layer of enforcement. Re-run auth.py to widen it.

Voting is in full rather than write because automated voting is the part of Reddit's API terms enforced most aggressively.

Tools

Tool	Tier	Purpose
reddit_me	read	Account summary: karma, age, moderated subreddits
reddit_feed	read	The subscribed front page
reddit_subreddit	read	Posts in one subreddit
reddit_post	read	One post with its comment tree
reddit_search	read	Search all of Reddit or one subreddit
reddit_user	read	A user's posts and comments
reddit_inbox	read	Unread, all, mentions or sent
reddit_saved	read	Saved posts and comments
reddit_my_subreddits	read	Current subscriptions
reddit_submit	write	Post a link or self post
reddit_reply	write	Reply to a post or comment
reddit_edit	write	Edit your own post or comment
reddit_delete	write	Delete your own post or comment
reddit_mark_read	write	Mark inbox items read
reddit_vote	full	Upvote, downvote or clear
reddit_save	full	Save or unsave
reddit_subscribe	full	Subscribe or unsubscribe
reddit_modqueue	full	Items awaiting moderation
reddit_mod_action	full	Approve, remove, spam, lock, unlock

A target argument accepts a fullname (t3_abc, t1_xyz), a bare post ID, or a reddit URL. Bare IDs resolve to posts; pass comments as t1_ fullnames or URLs.

Configuration

Variable	Default	Meaning
REDDIT_MCP_SCOPE	write	Tier: read, write or full
REDDIT_MCP_MAX_BODY	4000	Character cap per body before truncation
REDDIT_MCP_CONFIG_DIR	~/.config/reddit-mcp	Credentials location
REDDIT_MCP_REDIRECT_URI	http://localhost:8080/callback	Must match the Reddit app
REDDIT_CLIENT_ID		Overrides the credentials file
REDDIT_REFRESH_TOKEN		Overrides the credentials file

Tests

./.venv/bin/python test/smoke.py

Starts the server over stdio and checks the tool count at each tier. Runs without credentials or network. Run it after bumping a pin in requirements.txt, since upstream renames show up as import or registration failures.

Live API behaviour is not covered, as that needs real credentials.

Notes

Versions are pinned. PRAW and the MCP SDK have both made breaking renames, such as FastMCP to MCPServer in mcp 2.0.

Reddit's free API tier allows 100 queries per minute per client ID, and listings page at 100 items.

PRAW bundles update-checker, which contacts PyPI on first use. The server disables it.

An agent posting under your account is still you as far as Reddit's moderators are concerned. Vote manipulation and spam violate the API terms.

Layout

src/config.py    Credentials and scope tiers
src/server.py    MCP stdio server and tool definitions
bin/auth.py      One time OAuth consent flow
bin/setup.sh     Creates the venv
test/smoke.py    Starts the server and checks tool counts per tier

License

MIT. See LICENSE.