Metadata-Version: 2.4
Name: 5mghost-rover
Version: 0.0.19
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 :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: 5mghost-shared-client>=0.0.2
Requires-Dist: curl-cffi>=0.7
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.25
Requires-Dist: playwright>=1.54
Description-Content-Type: text/markdown

# reddit-mcp

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

## Quick Start

```bash
# 0. One-line installer (macOS / Linux)
curl -fsSL https://mkterswingman.com/install/reddit-mcp.sh | bash

# 0b. One-line installer (Windows PowerShell)
irm https://mkterswingman.com/install/reddit-mcp.ps1 | iex

# 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

First-party local MCPs on the same machine now share one auth file at `~/.mkterswingman/auth.json`.
That means logging into `yt-mcp` or another first-party local MCP can satisfy `reddit-mcp` too. Reddit local state now lives under `~/.mkterswingman/reddit-mcp/`.

### PAT Setup (Simplest)

1. Visit https://mkterswingman.com/pat/login
2. Log in and generate a PAT
3. Either save it once through any first-party local MCP setup flow, or 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 [--shutdown-browser]` | Full setup: OAuth login + cookie setup |
| `reddit-mcp setup-cookies [--shutdown-browser]` | Cookie-only setup (already have a PAT) |
| `reddit-mcp uninstall` | Remove MCP registrations and local `~/.mkterswingman/reddit-mcp` config |
| `reddit-mcp update` | Check for updates and install latest version |
| `reddit-mcp install-skills` | Install/update bundled `use-reddit-mcp` skill in local AI clients |
| `reddit-mcp check` | Check token & cookie status |
| `reddit-mcp version` | Show version |

## Bundled Skill

The package includes a bundled skill `use-reddit-mcp` that helps AI clients route Reddit analysis requests to the right tools.

- `setup` installs the skill automatically
- `update` refreshes the installed skill
- You can manually run `reddit-mcp install-skills` at any time

## 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 `~/.mkterswingman/reddit-mcp/cookies.json` (permissions: 600).

- On macOS, `setup-cookies` first tries to import a reusable Reddit session from copied local Chrome / Edge profiles
- On Windows, Chromium now protects cookies from cross-profile reuse, so `setup-cookies` opens a dedicated local Chrome / Edge window and stores that Reddit login in `~/.mkterswingman/reddit-mcp/browser-profile`
- The Windows guided login flow avoids depending on your live Chrome / Edge profile state
- They're stored locally and **never uploaded to any server**
- If cookies expire (403 errors), `reddit-mcp` first tries a silent refresh path; if that fails, run `reddit-mcp setup-cookies` manually
- A warning is shown when cookies are close to expiry (or fallback age is very 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.11+
- Playwright browser runtime (run `playwright install chromium` once if missing)
- A valid PAT or OAuth token

## Verification

- Run `python3 -m pytest` for the normal automated suite
- Run [`docs/E2E_CHECKLIST.md`](/Users/yimingwang/ai-workspace/services/mcp-task-reddit-e2e/reddit-mcp/docs/E2E_CHECKLIST.md) before releasing install or cookie-flow changes

## License

MIT
