# 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

```bash
./bin/setup.sh
```

### 3. Authorize

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

```bash
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

```bash
./.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](LICENSE).