# Reddit MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives Claude access to Reddit. Browse subreddits, read posts and comments, search content, submit posts, comment, vote, and save — all from within Claude Code or any MCP-compatible client.

## Features

**12 tools** covering the full Reddit experience:

| Tool | Description |
|------|-------------|
| `get_subreddit_posts` | Get posts from a subreddit with sort/time filters and pagination |
| `get_subreddit_info` | Get subreddit metadata — subscribers, description, rules |
| `search_posts` | Search posts across Reddit or within a specific subreddit |
| `search_subreddits` | Search for subreddits by name or topic |
| `read_post` | Read a post and its comment tree with configurable depth |
| `get_user_profile` | Get a user's profile — karma, account age, bio |
| `get_user_posts` | Get posts submitted by a user |
| `get_user_comments` | Get comments posted by a user |
| `submit_post` | Submit a text or link post to a subreddit |
| `submit_comment` | Reply to a post or comment |
| `vote` | Upvote, downvote, or remove vote |
| `save_post` | Save or unsave a post or comment |

## Prerequisites

- **Java 21** or later
- **Maven 3.8+** (to build from source)
- A **Reddit account**

## Setup

### 1. Create a Reddit app

1. Go to [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps/)
2. Click **"create another app..."**
3. Fill in:
   - **name:** `MCP` (or anything you like)
   - **type:** select **installed app**
   - **redirect uri:** `http://localhost:PORT/callback` (the setup wizard will tell you the exact port)
4. Click **create app**
5. Copy the **client ID** shown under the app name

### 2. Build

```bash
git clone https://github.com/wrxck/reddit-mcp.git
cd reddit-mcp
mvn clean package -DskipTests
```

This produces `target/reddit-mcp-1.0.0.jar` — a self-contained executable JAR.

### 3. Run setup

```bash
java -jar target/reddit-mcp-1.0.0.jar --init
```

This will:
- Prompt for your Reddit client ID
- Save config to `~/.reddit-mcp/config.properties`
- Open your browser for Reddit OAuth authorisation
- Save tokens to `~/.reddit-mcp/tokens.json`
- Register the server with Claude Code automatically

### 4. Restart Claude Code

The `reddit` MCP server will be available in your next Claude Code session.

## Usage

Once set up, Claude can use Reddit tools naturally:

```
> What's trending on r/programming right now?
> Search Reddit for discussions about MCP servers
> Read the comments on that top post
> What has u/spez posted recently?
```

Write operations require confirmation before executing:

```
> Upvote that post
> Reply to that comment with "Great explanation, thanks!"
> Submit a post to r/test titled "Hello from MCP"
```

## Manual registration

If automatic registration didn't work, register manually:

```bash
claude mcp add --scope user --transport stdio reddit -- \
  java -jar /path/to/reddit-mcp-1.0.0.jar
```

## Re-authenticate

If your Reddit tokens expire or you need to switch accounts:

```bash
java -jar target/reddit-mcp-1.0.0.jar --auth
```

## Security

- **Content sanitization** — All Reddit content (titles, post bodies, comments, usernames) is wrapped in unique boundary markers with instructions to treat it as untrusted data. This defends against prompt injection via Reddit content.
- **Token storage** — OAuth tokens and config files are stored with `600` POSIX permissions (owner read/write only).
- **Input validation** — Subreddit names, usernames, and thing IDs are validated against strict regex patterns before any API call.
- **CSRF protection** — The OAuth flow uses cryptographic state parameters to prevent cross-site request forgery.

## Rate limiting

The server enforces two layers of rate limiting:

1. **Local** — Max 55 requests/minute (below Reddit's 60/minute limit), tracked via a sliding window.
2. **Server** — Respects `X-Ratelimit-Remaining` and `X-Ratelimit-Reset` headers from Reddit. Automatically waits when approaching the server-side limit.

## Building from source

```bash
mvn clean verify
```

This compiles, runs all 126 tests, and produces the shaded JAR.

## Project structure

```
src/main/java/com/reddit/mcp/
├── RedditMcpServer.java     # Entry point, CLI args, server wiring
├── RedditClient.java        # HTTP client, token management, API methods
├── RedditAuth.java          # OAuth2 flow, config/token persistence
├── RedditTools.java         # 8 read-only MCP tool definitions
├── RedditWriteTools.java    # 4 write MCP tool definitions
├── ResponseParser.java      # Reddit JSON → structured maps
├── ContentSanitizer.java    # Prompt injection defence
├── Validation.java          # Input validation (regex patterns)
├── RateLimiter.java         # Dual-layer rate limiting
├── ResultHelper.java        # MCP result formatting utilities
└── ClaudeRegistration.java  # Auto-registration with Claude Code
```

## License

[MIT](LICENSE)