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

Related MCP server: reddit-mcp

Permission tiers

REDDIT_MCP_SCOPE selects the tier. Default is write.

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

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

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.