# Reddit MCP Server

A personal, read-only MCP (Model Context Protocol) server that provides access to Reddit's API through any MCP-compatible client (Claude Desktop, Claude Code, etc.).

## What It Does

This server exposes 8 tools for interacting with Reddit:

| Tool | Description |
|------|-------------|
| `reddit_search` | Search all of Reddit or a specific subreddit by keyword |
| `reddit_browse_subreddit` | Browse posts in a subreddit (hot, new, top, rising) |
| `reddit_get_post` | Fetch a post and its comments by ID or URL |
| `reddit_get_user_posts` | Get posts by a user (or yourself) |
| `reddit_get_user_comments` | Get comments by a user (or yourself) |
| `reddit_get_saved` | List your saved posts and comments |
| `reddit_get_subscriptions` | List your subscribed subreddits |
| `reddit_get_subreddit_info` | Get metadata and rules for a subreddit |

All tools are **read-only**. The server does not post, comment, vote, moderate, or modify any Reddit content.

## Requirements

- Python 3.10+
- A Reddit account
- Reddit API credentials (see Setup below)

## Setup

### 1. Get Reddit API Credentials

1. Go to [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps)
2. Click **"create another app..."**
3. Select **"script"** as the app type
4. Set redirect URI to `http://localhost:8080`
5. Note your **Client ID** (string under the app name) and **Client Secret**

### 2. Install Dependencies

```bash
cd reddit-mcp-server

# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. Configure Credentials

Copy the example env file and fill in your credentials:

```bash
cp .env.example .env
```

Edit `.env` with your values:

```
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USERNAME=your_reddit_username
REDDIT_PASSWORD=your_reddit_password
```

**Security:** The `.env` file is in `.gitignore` and will not be committed. Never put credentials in source code.

### 4. Connect to Claude Desktop

Add this to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "reddit": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/reddit-mcp-server/server.py"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password"
      }
    }
  }
}
```

Replace the paths and credentials with your actual values.

## Security

This server follows secure coding principles:

- **No hardcoded secrets.** All credentials are loaded from environment variables at startup.
- **Fail closed.** Missing credentials cause immediate exit — the server will not start in a broken state.
- **Input validation.** All tool inputs are validated with Pydantic (type, length, format) before any API call.
- **Minimal data exposure.** Responses return only relevant fields — no raw API objects or credential leakage.
- **Sanitized subreddit/user names.** Inputs are checked for injection characters before use.
- **Safe error handling.** Errors return actionable messages without stack traces or internal details.
- **Read-only operation.** No tool modifies Reddit content. All tools are annotated with `readOnlyHint: true`.

## Rate Limits

Reddit's free tier allows 60–100 requests per minute for OAuth-authenticated apps. Normal conversational use through an MCP client will stay well within these limits.

## License

MIT