# reddit-mcp

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

## Quick Start

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

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

```bash
# Direct install without hosted installer
uv tool install 5mghost-rover

# Full setup (auth + Reddit cookies + AI client registration)
reddit-mcp setup
```

Add this runtime command to AI clients that need manual config:

```json
{
  "mcpServers": {
    "reddit-mcp": {
      "command": "reddit-mcp",
      "args": ["serve"]
    }
  }
}
```

## 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

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 `reddit-mcp setup-cookies` to set up Reddit cookies

### Full Setup

```bash
reddit-mcp setup
```

This runs auth, cookie setup, AI client registration, and final verification in one flow.

## 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 your installed Chrome / Edge executable with a dedicated `reddit-mcp` browser profile stored at `~/.mkterswingman/reddit-mcp/browser-profile`
- The Windows guided login flow avoids depending on your live Chrome / Edge profile state while still using a real local browser that Reddit accepts for interactive login
- 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`.

- Supported install path: `uv tool install 5mghost-rover`
- Supported runtime command: `reddit-mcp serve`
- Supported setup entrypoint: `reddit-mcp setup`

## Requirements

- `uv` (the hosted installer can install it automatically)
- On Windows, a local Google Chrome or Microsoft Edge installation for interactive cookie setup
- A valid PAT or OAuth token

You do not need to preinstall Python when using the supported `uv` path.

## Troubleshooting

- If `reddit-mcp setup` fails during auth, visit https://mkterswingman.com/pat/login and retry.
- If no AI client is auto-detected, keep using `reddit-mcp serve` as the manual MCP command.
- If cookies expire or Reddit starts returning 403s, rerun `reddit-mcp setup-cookies`.

## 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
