Content
# Reddit Explorer MCP
An [MCP](https://modelcontextprotocol.io) server that gives AI agents read **and** write access to Reddit via [PRAW](https://praw.readthedocs.io/). Run it locally with `uvx` — no clone required.
## Features
**Read (works in read-only mode):**
- `search_reddit` — full-text search across all of Reddit or a single subreddit (supports `flair:`, `author:`, `self:` syntax)
- `get_subreddit_posts` — hot / new / top / controversial / rising listings, with optional flair filter
- `get_subreddit_flairs` — list available post flairs
- `get_subreddit_info` — metadata, rules, moderators
- `get_submission` / `get_post_comments` — full post details and threaded comment trees
- `get_redditor_info` — user profile + optional recent activity
- `get_front_page` / `get_popular` / `get_all` — front-page / popular / all listings
- `search_subreddits` / `get_default_subreddits`
**Write (requires authenticated credentials):**
- `submit_post` — submit a text or link post
- `submit_comment` — comment on a post or reply to a comment
- `vote` — upvote / downvote / clear
- `save_post` — save / unsave
- `get_authenticated_user`
## Quick start
1. Create a Reddit app at <https://www.reddit.com/prefs/apps> (type: **script**).
2. Set credentials in your environment or a `.env` file (see `.env.example`):
```bash
REDDIT_CLIENT_ID=...
REDDIT_CLIENT_SECRET=...
REDDIT_USER_AGENT=reddit-explorer-mcp/0.1 by <your_username>
# Optional, for write access:
REDDIT_USERNAME=...
REDDIT_PASSWORD=...
```
3. Run with `uvx` (stdio transport, the default for local MCP clients):
```bash
uvx reddit-explorer-mcp
```
Or run an HTTP server:
```bash
uvx reddit-explorer-mcp --transport http --host 0.0.0.0 --port 8000
```
## Client configuration
### Claude Desktop / Claude Code (`stdio`)
```json
{
"mcpServers": {
"reddit": {
"command": "uvx",
"args": ["reddit-explorer-mcp"],
"env": {
"REDDIT_CLIENT_ID": "...",
"REDDIT_CLIENT_SECRET": "...",
"REDDIT_USER_AGENT": "reddit-explorer-mcp/0.1 by <your_username>"
}
}
}
}
```
### HTTP transport
```json
{
"mcpServers": {
"reddit": {
"url": "http://localhost:8000/mcp"
}
}
}
```
## Development
```bash
uv sync
uv run reddit-mcp --help
uv run pytest
```
## License
MIT
