# Reddit MCP Server

[![PyPI version](https://badge.fury.io/py/reddit-mcp.svg)](https://pypi.org/project/reddit-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server providing 85+ tools for Reddit API access via [PRAW](https://praw.readthedocs.io/).

## Features

- **Reading**: Browse posts, comments, subreddits, user profiles, wiki pages
- **Submissions**: Create text/link/image/video/gallery/poll posts, crosspost
- **Comments**: Reply, edit, delete comments
- **Interactions**: Vote, save, hide, report, award content
- **Search**: Search posts, comments, users across Reddit
- **User Management**: Friends, blocks, preferences, multireddits
- **Moderation**: Full mod tools - approve/remove, ban/mute, flair, modqueue

## Installation

### Option 1: PyPI (Recommended)

```bash
# With pip
pip install reddit-mcp

# With uv
uv pip install reddit-mcp
```

### Option 2: uvx (No Installation)

Run directly without installing:

```bash
uvx reddit-mcp
```

### Option 3: From GitHub

```bash
# With pip
pip install git+https://github.com/ErcinDedeoglu/reddit-mcp.git

# With uv
uv pip install git+https://github.com/ErcinDedeoglu/reddit-mcp.git

# Or run directly with uvx
uvx --from git+https://github.com/ErcinDedeoglu/reddit-mcp.git reddit-mcp
```

### Option 4: From Source

```bash
git clone https://github.com/ErcinDedeoglu/reddit-mcp.git
cd reddit-mcp
uv sync  # or: pip install -e .
```

## Configuration

Create a `.env` file or set environment variables with your Reddit API credentials:

```env
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USERNAME=your_username
REDDIT_PASSWORD=your_password
REDDIT_USER_AGENT=reddit-mcp/1.0.0
```

### Getting Reddit API Credentials

1. Go to https://www.reddit.com/prefs/apps
2. Click "create another app..."
3. Select "script" type
4. Note the client ID (under app name) and secret

## Usage

### With Claude Desktop

Add to your Claude Desktop config:

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

#### Using PyPI install:

```json
{
  "mcpServers": {
    "reddit": {
      "command": "reddit-mcp",
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "REDDIT_USER_AGENT": "reddit-mcp/1.0.0"
      }
    }
  }
}
```

#### Using uvx (no install needed):

```json
{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": ["reddit-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "REDDIT_USER_AGENT": "reddit-mcp/1.0.0"
      }
    }
  }
}
```

#### Using local clone:

```json
{
  "mcpServers": {
    "reddit": {
      "command": "uv",
      "args": ["--directory", "/path/to/reddit-mcp", "run", "reddit-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "REDDIT_USER_AGENT": "reddit-mcp/1.0.0"
      }
    }
  }
}
```

### Standalone

```bash
# After installation
reddit-mcp

# With uvx
uvx reddit-mcp

# From source
uv run reddit-mcp
```

## Tools (85 total)

### Reading (13 tools)
| Tool | Description |
|------|-------------|
| `get_subreddit_posts` | Browse posts from any subreddit |
| `get_front_page` | Get posts from subscribed subreddits |
| `get_post_details` | Get full details of a post |
| `get_post_comments` | Get comments on a post |
| `get_comment_details` | Get a specific comment |
| `get_comment_replies` | Get replies to a comment |
| `get_subreddit_info` | Get subreddit metadata |
| `get_subreddit_rules` | Get posting rules |
| `get_subreddit_wiki_page` | Read wiki pages |
| `get_user_info` | Get user profile |
| `get_user_posts` | Browse user's posts |
| `get_user_comments` | Browse user's comments |
| `get_multireddit` | Get posts from multireddit |

### Submissions (9 tools)
| Tool | Description |
|------|-------------|
| `submit_text_post` | Create a text/self post |
| `submit_link_post` | Submit a URL |
| `submit_image_post` | Upload and post an image |
| `submit_video_post` | Upload and post a video |
| `submit_gallery_post` | Post multiple images |
| `submit_poll_post` | Create a poll |
| `edit_post` | Edit post content |
| `delete_post` | Delete a post |
| `crosspost` | Share to another subreddit |

### Comments (5 tools)
| Tool | Description |
|------|-------------|
| `reply_to_post` | Add a comment to a post |
| `reply_to_comment` | Reply to a comment |
| `edit_comment` | Edit your comment |
| `delete_comment` | Delete your comment |
| `get_more_comments` | Expand collapsed threads |

### Interactions (10 tools)
| Tool | Description |
|------|-------------|
| `upvote` | Upvote a post/comment |
| `downvote` | Downvote a post/comment |
| `clear_vote` | Remove your vote |
| `save_item` | Save to your account |
| `unsave_item` | Remove from saved |
| `hide_post` | Hide from your feed |
| `unhide_post` | Unhide a post |
| `report_item` | Report to moderators |
| `give_award` | Give an award |
| `get_saved_items` | List saved content |

### Search (4 tools)
| Tool | Description |
|------|-------------|
| `search_all` | Search all of Reddit |
| `search_subreddit` | Search within a subreddit |
| `search_comments` | Search comments |
| `search_users` | Find users |

### User (16 tools)
| Tool | Description |
|------|-------------|
| `get_me` | Get authenticated user info |
| `get_user` | Get any user's profile |
| `get_user_submissions` | Get user's post history |
| `get_karma_breakdown` | Karma by subreddit |
| `get_trophies` | User's trophies |
| `get_friends` | List friends |
| `add_friend` | Add a friend |
| `remove_friend` | Remove a friend |
| `get_blocked` | List blocked users |
| `block_user` | Block a user |
| `unblock_user` | Unblock a user |
| `get_preferences` | Get account settings |
| `update_preferences` | Update settings |
| `get_multireddits` | List your multireddits |
| `create_multireddit` | Create a multireddit |
| `is_username_available` | Check username availability |

### Moderation (28 tools)
| Tool | Description |
|------|-------------|
| `approve_item` | Approve reported content |
| `remove_item` | Remove content |
| `spam_item` | Mark as spam |
| `distinguish_comment` | Add mod distinction |
| `undistinguish_comment` | Remove distinction |
| `sticky_post` | Sticky a post |
| `unsticky_post` | Unsticky a post |
| `set_suggested_sort` | Set comment sort |
| `ban_user` | Ban from subreddit |
| `unban_user` | Remove ban |
| `mute_user` | Mute in modmail |
| `unmute_user` | Unmute user |
| `add_contributor` | Add approved user |
| `remove_contributor` | Remove approved user |
| `get_banned` | List banned users |
| `get_contributors` | List approved users |
| `set_user_flair` | Set user's flair |
| `delete_user_flair` | Remove user flair |
| `set_post_flair` | Set post flair |
| `get_flair_templates` | List flair options |
| `create_flair_template` | Create new flair |
| `delete_flair_template` | Delete flair option |
| `get_modqueue` | View mod queue |
| `get_reports` | View reported items |
| `get_spam` | View spam queue |
| `get_edited` | View edited items |
| `get_unmoderated` | View unmoderated posts |
| `get_mod_log` | View moderation log |

## Development

```bash
# Clone and install with dev dependencies
git clone https://github.com/ErcinDedeoglu/reddit-mcp.git
cd reddit-mcp
uv sync --dev

# Run linters
uv run ruff check .
uv run pylint reddit_mcp/

# Build package
uv build
```

## Publishing to PyPI

```bash
# Build the package
uv build

# Publish (requires PYPI_TOKEN)
uv publish
```

## License

MIT License - see [LICENSE](LICENSE) for details.
