Metadata-Version: 2.4
Name: reddit-explorer-mcp
Version: 0.1.0
Summary: MCP server that exposes Reddit browsing and posting to AI agents via PRAW.
Project-URL: Homepage, https://github.com/bhavik/Reddit-MCP
Project-URL: Issues, https://github.com/bhavik/Reddit-MCP/issues
Author: Bhavik
License: MIT
Keywords: agent,ai,llm,mcp,model-context-protocol,praw,reddit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.27
Requires-Dist: praw>=8.0
Requires-Dist: python-dotenv>=1.0
Description-Content-Type: text/markdown

# 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