Metadata-Version: 2.4
Name: 5mghost-rover
Version: 0.0.3
Summary: Reddit MCP server — access Reddit data through MCP protocol
Project-URL: Homepage, https://github.com/mkterswingman/mcp_projects
Author: mkterswingman
License-Expression: MIT
Keywords: ai,llm,mcp,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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: browser-use>=0.12
Requires-Dist: curl-cffi>=0.7
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.25
Description-Content-Type: text/markdown

# reddit-mcp

Reddit MCP server — access Reddit data (posts, comments, search) through the MCP protocol.

## Quick Start

```bash
# 1. Full setup (OAuth login + Reddit cookies)
uvx --from 5mghost-rover reddit-mcp setup

# 2. Add to your AI client config (Claude Desktop, Cursor, etc.)
```

```json
{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": ["--from", "5mghost-rover", "reddit-mcp", "serve"],
      "env": {
        "REDDIT_MCP_TOKEN": "pat_xxx"
      }
    }
  }
}
```

## Authentication

reddit-mcp uses two layers of authentication:

1. **PAT / OAuth token** — Controls access to the MCP service (shared account system with yt-mcp / x-mcp)
2. **Reddit cookies** — Used to fetch data from Reddit's JSON API

### PAT Setup (Simplest)

1. Visit https://mkterswingman.com/pat/login
2. Log in and generate a PAT
3. Set `REDDIT_MCP_TOKEN=pat_xxx` in your MCP config's `env`
4. Run `uvx --from 5mghost-rover reddit-mcp setup-cookies` to set up Reddit cookies

### OAuth Setup (Full)

```bash
uvx --from 5mghost-rover reddit-mcp setup
```

This runs the OAuth flow and cookie setup in one step.

## CLI Commands

| Command | Description |
|---------|-------------|
| `reddit-mcp serve` | Start MCP server (stdio transport) |
| `reddit-mcp setup` | Full setup: OAuth login + cookie setup |
| `reddit-mcp setup-cookies` | Cookie-only setup (already have a PAT) |
| `reddit-mcp uninstall` | Remove MCP registrations and local `~/.reddit-mcp` config |
| `reddit-mcp update` | Check for updates and install latest version |
| `reddit-mcp check` | Check token & cookie status |
| `reddit-mcp version` | Show version |

## MCP Tools

### Data Tools

- **`get_subreddit_posts`** — Get posts from a subreddit (hot/new/top/rising, up to 100 per request)
- **`get_post_content`** — Get a post's content and comment tree
- **`search_reddit`** — Search Reddit posts (global or within a subreddit)
- **`get_subreddit_info`** — Get subreddit metadata (subscribers, description, etc.)

### Management Tools

- **`check_cookies`** — Check cookie validity, age, and username
- **`get_rate_limit_status`** — Check remaining API quota

## Rate Limits

Reddit allows 100 requests per 10-minute window. The client automatically:
- Reads `x-ratelimit-*` headers from responses
- Throttles when remaining quota < 20
- Retries on 429 (Too Many Requests)

For typical usage (1-10 requests per conversation), you'll never hit the limit.

## Cookie Management

Reddit cookies are stored at `~/.reddit-mcp/cookies.json` (permissions: 600).

- Cookies are obtained by launching Chrome and having you log in to Reddit
- They're stored locally and **never uploaded to any server**
- If cookies expire (403 errors), run `reddit-mcp setup-cookies` to refresh
- A warning is shown when cookies are > 7 days old

## Package Naming

The published PyPI package name is `5mghost-rover`, and the installed executable is `reddit-mcp`.

- `uvx --from 5mghost-rover reddit-mcp ...` works for one-off runs
- `pip install 5mghost-rover` installs the `reddit-mcp` command globally

## Requirements

- Python 3.10+
- Chrome browser (for `setup` / `setup-cookies` commands)
- A valid PAT or OAuth token

## License

MIT
