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

- Cookie setup/import always works on a copied local browser profile (Chrome/Edge/Chromium), never on your live browser process
- If a reusable Reddit session already exists in local browser profiles, `setup-cookies` imports it headlessly
- If no reusable session is found, `setup-cookies` opens a copied profile window for manual Reddit login
- They're stored locally and **never uploaded to any server**
- If cookies expire (403 errors), `reddit-mcp` first tries headless re-import from local profiles; 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

## License

MIT
